xref: /illumos-gate/usr/src/uts/common/sys/sata/sata_hba.h (revision 7f698155b6fd0ee137eb4a2e7c85f0915a94bfee)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License (the "License").
6  * You may not use this file except in compliance with the License.
7  *
8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9  * or http://www.opensolaris.org/os/licensing.
10  * See the License for the specific language governing permissions
11  * and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL HEADER in each
14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15  * If applicable, add the following below this CDDL HEADER, with the
16  * fields enclosed by brackets "[]" replaced with your own identifying
17  * information: Portions Copyright [yyyy] [name of copyright owner]
18  *
19  * CDDL HEADER END
20  */
21 
22 /*
23  * Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
24  * Use is subject to license terms.
25  */
26 /*
27  * Copyright 2015 Nexenta Systems, Inc.  All rights reserved.
28  */
29 
30 #ifndef _SATA_HBA_H
31 #define	_SATA_HBA_H
32 
33 #ifdef	__cplusplus
34 extern "C" {
35 #endif
36 
37 #include <sys/sata/sata_defs.h>
38 
39 /*
40  * SATA Host Bus Adapter (HBA) driver transport definitions
41  */
42 
43 #include <sys/types.h>
44 
45 #ifndef	TRUE
46 #define	TRUE	1
47 #define	FALSE	0
48 #endif
49 
50 #define	SATA_SUCCESS	0
51 #define	SATA_RETRY	1
52 #define	SATA_FAILURE	-1
53 
54 
55 /* SATA Framework definitions */
56 
57 #define	SATA_MAX_CPORTS		32	/* Max number of controller ports */
58 					/* Multiplier (PMult) */
59 #define	SATA_MAX_PMPORTS	16	/* Maximum number of ports on PMult */
60 #define	SATA_PMULT_HOSTPORT	0xf	/* Port Multiplier host port number */
61 
62 
63 /*
64  * SATA device address
65  * Address qualifier flags are used to specify what is addressed (device
66  * or port) and where (controller or port multiplier data port).
67  */
68 struct sata_address {
69 	uint8_t		cport;		/* Controller's SATA port number */
70 	uint8_t		pmport;		/* Port Multiplier SATA port number */
71 	uint8_t		qual;		/* Address Qualifier flags */
72 	uint8_t		pad;		/* Reserved */
73 };
74 
75 typedef struct sata_address sata_address_t;
76 
77 /*
78  * SATA address Qualifier flags (in qual field of sata_address struct).
79  * They are mutually exclusive.
80  */
81 
82 #define	SATA_ADDR_NULL		0x00	/* No address */
83 #define	SATA_ADDR_DCPORT	0x01	/* Device attched to controller port */
84 #define	SATA_ADDR_DPMPORT	0x02	/* Device attched to PM device port */
85 #define	SATA_ADDR_CPORT		0x04	/* Controller's device port */
86 #define	SATA_ADDR_PMPORT	0x08	/* Port Multiplier's device port */
87 #define	SATA_ADDR_CNTRL		0x10	/* Controller */
88 #define	SATA_ADDR_PMULT		0x20	/* Port Multiplier */
89 #define	SATA_ADDR_PMULT_SPEC	0x40	/* Port Multiplier Specific */
90 
91 /*
92  * SATA port status and control register block.
93  * The sstatus, serror, scontrol, sactive and snotific
94  * are the copies of the SATA port status and control registers.
95  * (Port SStatus, SError, SControl, SActive and SNotification are
96  * defined by Serial ATA r1.0a sepc and Serial ATA II spec.
97  */
98 
99 struct sata_port_scr
100 {
101 	uint32_t	sstatus;	/* Port SStatus register */
102 	uint32_t	serror;		/* Port SError register */
103 	uint32_t	scontrol;	/* Port SControl register */
104 	uint32_t	sactive;	/* Port SActive register */
105 	uint32_t	snotific;	/* Port SNotification register */
106 };
107 
108 typedef struct sata_port_scr sata_port_scr_t;
109 
110 /*
111  * SATA Port Multiplier general status and control register block.
112  * The gscr0, gscr1, gscr2 are the copyies of the register on port multiplier.
113  * GSCR[0], GSCR[1], GSCR[2] are defined in SATA defined by Port Multiplier
114  * 1.0/1.1/1.2 spec.
115  */
116 struct sata_pmult_gscr {
117 	uint32_t	gscr0;		/* Product Identifier register */
118 	uint32_t	gscr1;		/* Resrved Information register */
119 	uint32_t	gscr2;		/* Port Information register */
120 	uint32_t	gscr64;		/* Feature register */
121 	uint32_t	resv[4];	/* Reseved */
122 };
123 
124 typedef struct sata_pmult_gscr sata_pmult_gscr_t;
125 
126 /*
127  * SATA Device Structure (rev 1)
128  * Used to request/return state of the controller, port, port multiplier
129  * or an attached drive:
130  *	The satadev_addr.cport, satadev_addr.pmport and satadev_addr.qual
131  *	fields are used to specify SATA address (see sata_address structure
132  *	description).
133  *	The satadev_scr structure is used to pass the content of a port
134  *	status and control registers.
135  *	The satadev_add_info field is used by SATA HBA driver to return an
136  *	additional information, which type depends on the function using
137  *	sata_device as argument. For example:
138  *	- in case of sata_tran_probe_port() this field should contain
139  *	a number of available Port Multiplier device ports;
140  *	- in case of sata_hba_event_notify() this field may contain
141  *	a value specific for a reported event.
142  */
143 #define	SATA_DEVICE_REV_1	1
144 #define	SATA_DEVICE_REV		SATA_DEVICE_REV_1
145 
146 struct sata_device
147 {
148 	int		satadev_rev;		/* structure  version */
149 	struct sata_address satadev_addr;	/* sata port/device address */
150 	uint32_t	satadev_state;		/* Port or device state */
151 	uint32_t	satadev_type;		/* Attached device type */
152 	struct sata_port_scr satadev_scr;	/* Port status and ctrl regs */
153 	uint32_t	satadev_add_info;	/* additional information, */
154 						/* function specific */
155 };
156 
157 typedef struct sata_device sata_device_t;
158 
159 _NOTE(SCHEME_PROTECTS_DATA("unshared data", sata_device))
160 
161 
162 /*
163  * satadev_state field of sata_device structure.
164  * Common flags specifying current state of a port or an attached drive.
165  * These states are mutually exclusive, obviously
166  */
167 #define	SATA_STATE_UNKNOWN		0x000000
168 #define	SATA_STATE_READY		0x000010
169 
170 /*
171  * Attached drive specific states (satadev_state field of the sata_device
172  * structure).
173  * SATA_DSTATE_PWR_ACTIVE, SATA_DSTATE_PWR_IDLE and SATA_DSTATE_PWR_STANDBY
174  * are mutually exclusive. All other states may be combined with each other
175  * and with one of the power states.
176  * These flags may be used only if the address qualifier (satadev_addr.qual) is
177  * set to SATA_ADDR_DCPORT or SATA_ADDR_DPMPORT value.
178  */
179 
180 #define	SATA_DSTATE_PWR_ACTIVE		0x000100
181 #define	SATA_DSTATE_PWR_IDLE		0x000200
182 #define	SATA_DSTATE_PWR_STANDBY		0x000400
183 #define	SATA_DSTATE_RESET		0x001000
184 #define	SATA_DSTATE_PMULT_INIT		0x002000
185 #define	SATA_DSTATE_FAILED		0x008000
186 
187 /* Mask for drive power states */
188 #define	SATA_DSTATE_PWR			(SATA_DSTATE_PWR_ACTIVE | \
189 					SATA_DSTATE_PWR_IDLE | \
190 					SATA_DSTATE_PWR_STANDBY)
191 /*
192  * SATA Port specific states (satadev_state field of sata_device structure).
193  * SATA_PSTATE_PWRON and SATA_PSTATE_PWROFF are mutually exclusive.
194  * All other states may be combined with each other and with one of the power
195  * level state.
196  * These flags may be used only if the address qualifier (satadev_addr.qual) is
197  * set to SATA_ADDR_CPORT or SATA_ADDR_PMPORT value.
198  */
199 
200 #define	SATA_PSTATE_PWRON		0x010000
201 #define	SATA_PSTATE_PWROFF		0X020000
202 #define	SATA_PSTATE_SHUTDOWN		0x040000
203 #define	SATA_PSTATE_FAILED		0x080000
204 
205 /* Mask for the valid port-specific state flags */
206 #define	SATA_PSTATE_VALID		(SATA_PSTATE_PWRON | \
207 					SATA_PSTATE_PWROFF | \
208 					SATA_PSTATE_SHUTDOWN | \
209 					SATA_PSTATE_FAILED)
210 
211 /* Mask for a port power states */
212 #define	SATA_PSTATE_PWR			(SATA_PSTATE_PWRON | \
213 					SATA_PSTATE_PWROFF)
214 /*
215  * Device type (in satadev_type field of sata_device structure).
216  * More device types may be added in the future.
217  */
218 
219 #define	SATA_DTYPE_NONE			0x00	/* No device attached */
220 #define	SATA_DTYPE_ATADISK		0x01	/* ATA disk */
221 #define	SATA_DTYPE_ATAPI		0x40	/* ATAPI device */
222 #define	SATA_DTYPE_ATAPICD	\
223 	(SATA_DTYPE_ATAPI|0x02)			/* ATAPI CD/DVD device */
224 #define	SATA_DTYPE_ATAPITAPE	\
225 	(SATA_DTYPE_ATAPI|0x04)			/* ATAPI tape */
226 #define	SATA_DTYPE_ATAPIDISK	\
227 	(SATA_DTYPE_ATAPI|0x08)			/* ATAPI disk */
228 #define	SATA_DTYPE_PMULT		0x10	/* Port Multiplier */
229 #define	SATA_DTYPE_UNKNOWN		0x20	/* Device attached, unkown */
230 #define	SATA_DTYPE_ATAPIPROC	\
231 	(SATA_DTYPE_ATAPI|0x80)			/* ATAPI processor */
232 
233 
234 /*
235  * SATA cmd structure  (rev 1)
236  *
237  * SATA HBA framework always sets all fields except status_reg and error_reg.
238  * SATA HBA driver action depends on the addressing type specified by
239  * addr_type field:
240  * If LBA48 addressing is indicated, SATA HBA driver has to load values from
241  * satacmd_sec_count_msb_reg, satacmd_lba_low_msb_reg,
242  * satacmd_lba_mid_msb_reg and satacmd_lba_hi_msb_reg
243  * to appropriate registers prior to loading other registers.
244  * For other addressing modes, SATA HBA driver should skip loading values
245  * from satacmd_sec_count_msb_reg, satacmd_lba_low_msb_reg,
246  * satacmd_lba_mid_msb_reg and satacmd_lba_hi_msb_reg
247  * fields and load only remaining field values to corresponding registers.
248  *
249  * satacmd_sec_count_msb and satamcd_sec_count_lsb values are loaded into
250  * sec_count register, satacmd_sec_count_msb loaded first (if LBA48
251  * addressing is used).
252  * satacmd_lba_low_msb and satacmd_lba_low_lsb values are loaded into the
253  * lba_low register, satacmd_lba_low_msb loaded first (if LBA48 addressing
254  * is used). The lba_low register is the newer name for the old
255  * sector_number register.
256  * satacmd_lba_mid_msb and satacmd_lba_mid_lsb values are loaded into lba_mid
257  * register, satacmd_lba_mid_msb loaded first (if LBA48 addressing is used).
258  * The lba_mid register is the newer name for the old cylinder_low register.
259  * satacmd_lba_high_msb and satacmd_lba_high_lsb values are loaded into
260  * the lba_high regster, satacmd_lba_high_msb loaded first (if LBA48
261  * addressing is used). The lba_high register  is a newer name for the old
262  * cylinder_high register.
263  *
264  * No addressing mode is selected when an ata command does not involve actual
265  * reading/writing data from/to the media (for example IDENTIFY DEVICE or
266  * SET FEATURE command), or the ATAPI PACKET command is sent.
267  * If ATAPI PACKET command is sent and tagged commands are used,
268  * SATA HBA driver has to provide and manage a tag value and
269  * set it into the sector_count register.
270  *
271  * Device Control register is not specified in sata_cmd structure - SATA HBA
272  * driver shall set it accordingly to current mode of operation (interrupt
273  * enable/disable).
274  *
275  * Buffer structure's b_flags should be used to determine the
276  * address type of b_un.b_addr. However, there is no need to allocate DMA
277  * resources for the buffer in SATA HBA driver.
278  * DMA resources for a buffer structure are allocated by the SATA HBA
279  * framework. Scatter/gather list is to be used only for DMA transfers
280  * and it should be based on the DMA cookies list.
281  *
282  * Upon completion of a command, SATA HBA driver has to update
283  * satacmd_status_reg and satacmd_error_reg to reflect the contents of
284  * the corresponding device status and error registers.
285  * If the command completed successfully, satacmd_flags.sata_copy_xxx flags
286  * specify what register fields should be updated in sata_cmd structure.
287  * If the command completed with error, SATA HBA driver has to update
288  * satacmd_sec_count_msb, satacmd_sec_count_lsb, satacmd_lba_low_msb,
289  * satacmd_lba_low_lsb, satacmd_lba_mid_msb, satacmd_lba_mid_lsb,
290  * satacmd_lba_high_msb and satacmd_lba_high_lsb to values read from the
291  * corresponding device registers.
292  * If an operation could not complete because of the port error, the
293  * sata_pkt.satapkt_device.satadev_scr structure has to be updated.
294  *
295  * If ATAPI PACKET command was sent and command completed with error,
296  * rqsense structure has to be filed by SATA HBA driver. The satacmd_arq_cdb
297  * points to pre-set request sense cdb that may be used for issuing request
298  * sense data from the device.
299  *
300  * The sata_max_queue_depth field specifies the maximum allowable queue depth
301  * minus one, i.e. for maximum queue depth of 32, sata_max_queue_depth would
302  * be set to value 0x1f.
303  * If FPDMA-type command was sent and command completed with error, the HBA
304  * driver may use pre-set command READ LOG EXTENDED command pointed to
305  * by satacmd_rle_sata_cmd field to retrieve error data from a device.
306  * Only ATA register fields of the sata_cmd are set-up for that purpose.
307  *
308  * If the READ MULTIPLIER command was specified in cmd_reg (command directed
309  * to a port multiplier host port rather then to an attached device),
310  * upon the command completion SATA HBA driver has to update_sector count
311  * and lba fields of the sata_cmd structure to values returned via
312  * command block registers (task file registers).
313  */
314 #define	SATA_CMD_REV_1	1
315 #define	SATA_CMD_REV_2	2
316 #define	SATA_CMD_REV_3	3
317 #define	SATA_CMD_REV	SATA_CMD_REV_3
318 
319 #define	SATA_ATAPI_MAX_CDB_LEN	16	/* Covers both 12 and 16 byte cdbs */
320 #define	SATA_ATAPI_RQSENSE_LEN	24	/* Allocated Request Sense data */
321 #define	SATA_ATAPI_MIN_RQSENSE_LEN 18	/* Min Fixed size Request Sense data */
322 #define	SATA_ATAPI_RQSENSE_CDB_LEN 6	/* Request Sense CDB length */
323 
324 #define	SATA_MAX_QUEUE_DEPTH	32	/* Default max queue depth */
325 
326 struct sata_cmd {
327 	int		satacmd_rev;		/* version */
328 	struct buf	*satacmd_bp;		/* ptr to buffer structure */
329 	struct sata_cmd_flags {
330 		uint32_t	sata_data_direction : 3;	 /* 0-2 */
331 		uint32_t	: 1;		/* reserved */	 /* 3 */
332 		uint32_t	sata_queue_stag : 1;		 /* 4 */
333 		uint32_t	sata_queue_otag : 1;		 /* 5 */
334 		uint32_t	: 2;		/* reserved */	 /* 6-7 */
335 		uint32_t	sata_queued : 1;		 /* 8 */
336 		uint32_t	: 3;		/* reserved */	 /* 9-11 */
337 		uint32_t	sata_ignore_dev_reset : 1;	 /* 12 */
338 		uint32_t	sata_clear_dev_reset : 1;	 /* 13 */
339 		uint32_t	: 2;		/* reserved */	 /* 14-15 */
340 		uint32_t	sata_special_regs : 1;		 /* 16 */
341 		uint32_t	sata_copy_out_sec_count_msb : 1; /* 17 */
342 		uint32_t	sata_copy_out_lba_low_msb : 1;	 /* 18 */
343 		uint32_t	sata_copy_out_lba_mid_msb : 1;	 /* 19 */
344 		uint32_t	sata_copy_out_lba_high_msb : 1;	 /* 20 */
345 		uint32_t	sata_copy_out_sec_count_lsb : 1; /* 21 */
346 		uint32_t	sata_copy_out_lba_low_lsb : 1;	 /* 22 */
347 		uint32_t	sata_copy_out_lba_mid_lsb : 1;	 /* 23 */
348 		uint32_t	sata_copy_out_lba_high_lsb : 1;	 /* 24 */
349 		uint32_t	sata_copy_out_device_reg : 1;	 /* 25 */
350 		uint32_t	sata_copy_out_error_reg : 1;	 /* 26 */
351 		uint32_t	sata_max_queue_depth: 5;	 /* 27-31 */
352 	} satacmd_flags;
353 	uint8_t		satacmd_addr_type;	/* addr type: LBA28, LBA48 */
354 	uint8_t		satacmd_features_reg_ext; /* features reg extended */
355 	uint8_t		satacmd_sec_count_msb;	/* sector count MSB (LBA48) */
356 	uint8_t		satacmd_lba_low_msb;	/* LBA Low MSB (LBA48) */
357 	uint8_t		satacmd_lba_mid_msb;	/* LBA Mid MSB (LBA48) */
358 	uint8_t		satacmd_lba_high_msb;	/* LBA High MSB (LBA48) */
359 	uint8_t		satacmd_sec_count_lsb;	/* sector count LSB */
360 	uint8_t		satacmd_lba_low_lsb;	/* LBA Low LSB */
361 	uint8_t		satacmd_lba_mid_lsb;	/* LBA Mid LSB */
362 	uint8_t		satacmd_lba_high_lsb;	/* LBA High LSB */
363 	uint8_t		satacmd_device_reg;	/* ATA dev reg & LBA28 MSB */
364 	uint8_t		satacmd_cmd_reg;	/* ata command code */
365 	uint8_t		satacmd_features_reg;	/* ATA features register */
366 	uint8_t		satacmd_status_reg;	/* ATA status register */
367 	uint8_t		satacmd_error_reg;	/* ATA error register  */
368 	uint8_t		satacmd_acdb_len;	/* ATAPI cdb length */
369 	uint8_t		satacmd_acdb[SATA_ATAPI_MAX_CDB_LEN]; /* ATAPI cdb */
370 
371 						/* kept for binary compat. */
372 	uint8_t		*pad1;			/* unused */
373 
374 	uint8_t		satacmd_rqsense[SATA_ATAPI_RQSENSE_LEN];
375 						/*
376 						 * Error retrieval buffer
377 						 * dma handle pointer
378 						 * (for buffer DMA syncing)
379 						 * Valid only in error
380 						 * retrieval packet!
381 						 */
382 	ddi_dma_handle_t *satacmd_err_ret_buf_handle;
383 
384 	int		satacmd_num_dma_cookies; /* number of dma cookies */
385 						/* ptr to dma cookie list */
386 	ddi_dma_cookie_t *satacmd_dma_cookie_list;
387 };
388 
389 typedef struct sata_cmd sata_cmd_t;
390 
391 _NOTE(SCHEME_PROTECTS_DATA("unshared data", sata_cmd))
392 
393 
394 /* ATA address type (in satacmd_addr_type field */
395 #define	ATA_ADDR_LBA	0x1
396 #define	ATA_ADDR_LBA28	0x2
397 #define	ATA_ADDR_LBA48	0x4
398 
399 /*
400  * satacmd_flags : contain data transfer direction flags,
401  * tagged queuing type flags, queued command flag, and reset state handling
402  * flag.
403  */
404 
405 /*
406  * Data transfer direction flags (satacmd_flags.sata_data_direction)
407  * Direction flags are mutually exclusive.
408  */
409 #define	SATA_DIR_NODATA_XFER	0x0001	/* No data transfer */
410 #define	SATA_DIR_READ		0x0002	/* Reading data from a device */
411 #define	SATA_DIR_WRITE		0x0004	/* Writing data to a device */
412 
413 /*
414  * Tagged Queuing type flags
415  *	satacmd_flags.sata_queue_stag
416  *	satacmd_flags.sata_queue_otag
417  *
418  * These flags indicate how the SATA command should be queued.
419  *
420  * sata_queue_stag
421  * Simple-queue-tagged command. It may be executed out-of-order in respect
422  * to other queued commands.
423  * sata_queue_otag
424  * Ordered-queue-tagged command. It cannot be executed out-of-order in
425  * respect to other commands, i.e. it should be executed in the order of
426  * being transported to the HBA.
427  *
428  * Translated head-of-queue-tagged scsi commands and commands that are
429  * to be put at the head of the queue are treated as sata_queue_otag
430  * tagged commands.
431  */
432 
433 
434 /*
435  * Queuing command set-up flag (satacmd_flags.sata_queued).
436  * This flag indicates that sata_cmd was set-up for DMA Queued command
437  * (either READ_DMA_QUEUED, READ_DMA_QUEUED_EXT, WRITE_DMA_QUEUED or
438  * WRITE_DMA_QUEUED_EXT command) or one of the Native Command Queuing commands
439  * (either READ_FPDMA_QUEUED or WRITE_FPDMA_QUEUED).
440  * This flag will be used only if sata_tran_hba_flags indicates controller
441  * support for queuing and the device for which sata_cmd is prepared supports
442  * either legacy queuing (indicated by Device Identify data word 83 bit 2)
443  * or NCQ (indicated by  word 76 of Device Identify data).
444  */
445 
446 /*
447  * Reset state handling
448  *	satacmd_flags.sata_ignore_dev_reset
449  *	satacmd_flags.sata_clear_dev_reset
450  *
451  * SATA HBA device enters reset state if the device was subjected to
452  * the Device Reset (may also enter this state if the device was reset
453  * as a side effect of port reset). SATA HBA driver sets this state.
454  * Device stays in this condition until explicit request from SATA HBA
455  * framework to clear the state.
456  */
457 
458 /*
459  * SATA Packet structure (rev 1)
460  * hba_driver_private is for a private use of the SATA HBA driver;
461  * satapkt_framework_private is used only by SATA HBA framework;
462  * satapkt_comp is a callback function to be called when packet
463  * execution is completed (for any reason) if mode of operation is not
464  * synchronous (SATA_OPMODE_SYNCH);
465  * satapkt_reason specifies why the packet operation was completed
466  *
467  * NOTE: after the packet completion callback SATA HBA driver should not
468  * attempt to access any sata_pkt fields because sata_pkt is not valid anymore
469  * (it could have been destroyed).
470  * Since satapkt_hba_driver_private field cannot be retrieved, any hba private
471  * data respources allocated per packet and accessed via this pointer should
472  * either be freed before the completion callback is done, or the pointer has
473  * to be saved by the HBA driver before the completion callback.
474  */
475 #define	SATA_PKT_REV_1	1
476 #define	SATA_PKT_REV	SATA_PKT_REV_1
477 
478 struct sata_pkt {
479 	int		satapkt_rev;		/* version */
480 	struct sata_device satapkt_device;	/* Device address/type */
481 
482 						/* HBA driver private data */
483 	void		*satapkt_hba_driver_private;
484 
485 						/* SATA framework priv data */
486 	void		*satapkt_framework_private;
487 
488 						/* Rqsted mode of operation */
489 	uint32_t	satapkt_op_mode;
490 
491 	struct sata_cmd	satapkt_cmd;		/* composite sata command */
492 	int		satapkt_time;		/* time allotted to command */
493 	void		(*satapkt_comp)(struct sata_pkt *); /* callback */
494 	int		satapkt_reason;		/* completion reason */
495 };
496 
497 typedef struct sata_pkt sata_pkt_t;
498 
499 _NOTE(SCHEME_PROTECTS_DATA("unshared data", sata_pkt))
500 
501 
502 /*
503  * Operation mode flags (in satapkt_op_mode field of sata_pkt structure).
504  * Use to specify what should be a mode of operation for specified command.
505  * Default (000b) means use Interrupt and Asynchronous mode to
506  * perform an operation.
507  * Synchronous operation menas that the packet operation has to be completed
508  * before the function called to initiate the operation returns.
509  */
510 #define	SATA_OPMODE_INTERRUPTS	0 /* Use interrupts (hint) */
511 #define	SATA_OPMODE_POLLING	1 /* Use polling instead of interrupts */
512 #define	SATA_OPMODE_ASYNCH	0 /* Return immediately after accepting pkt */
513 #define	SATA_OPMODE_SYNCH	4 /* Perform synchronous operation */
514 
515 /*
516  * satapkt_reason values:
517  *
518  * SATA_PKT_QUEUE_FULL - cmd not sent because of queue full (detected
519  *	by the controller). If a device reject command for this reason, it
520  *	should be reported as SATA_PKT_DEV_ERROR
521  *
522  * SATA_PKT_CMD_NOT_SUPPORTED - command not supported by a controller
523  *	Controller is unable to send such command to a device.
524  *	If device rejects a command, it should be reported as
525  *	SATA_PKT_DEV_ERROR.
526  *
527  * SATA_PKT_DEV_ERROR - cmd failed because of device reported an error.
528  *	The content of status_reg (ERROR bit has to be set) and error_reg
529  *	fields of the sata_cmd structure have to be set and will be used
530  *	by SATA HBA Framework to determine the error cause.
531  *
532  * SATA_PKT_PORT_ERROR - cmd failed because of a link or a port error.
533  *	Link failed / no communication with a device / communication error
534  *	or other port related error was detected by a controller.
535  *	sata_pkt.satapkt_device.satadev_scr.sXXXXXXX words have to be set.
536  *
537  * SATA_PKT_ABORTED - cmd execution was aborted by the request from the
538  *	framework. Abort mechanism is HBA driver specific.
539  *
540  * SATA_PKT_TIMEOUT - cmd execution has timed-out. Timeout specified by
541  *	 pkt_time was exceeded. The command was terminated by the SATA HBA
542  *	driver.
543  *
544  * SATA_PKT_COMPLETED - this is a value returned when an operation
545  *	completes without errors.
546  *
547  * SATA_PKT_BUSY - packet was not accepted for execution because the
548  *      driver was busy performing some other operation(s).
549  *
550  * SATA_PKT_RESET - packet execution was aborted because of device
551  * reset originated by either the HBA driver or the SATA framework.
552  *
553  */
554 
555 #define	SATA_PKT_BUSY			-1	/* Not completed, busy */
556 #define	SATA_PKT_COMPLETED		0	/* No error */
557 #define	SATA_PKT_DEV_ERROR		1	/* Device reported error */
558 #define	SATA_PKT_QUEUE_FULL		2	/* Not accepted, queue full */
559 #define	SATA_PKT_PORT_ERROR		3	/* Not completed, port error */
560 #define	SATA_PKT_CMD_UNSUPPORTED	4	/* Cmd unsupported */
561 #define	SATA_PKT_ABORTED		5	/* Aborted by request */
562 #define	SATA_PKT_TIMEOUT		6	/* Operation timeut */
563 #define	SATA_PKT_RESET			7	/* Aborted by reset request */
564 
565 /*
566  * Error retrieval sata packet types
567  */
568 #define	SATA_ERR_RETR_PKT_TYPE_NCQ	1
569 #define	SATA_ERR_RETR_PKT_TYPE_ATAPI	2
570 
571 /*
572  * Read/write port multiplier packet types
573  */
574 #define	SATA_RDWR_PMULT_PKT_TYPE_READ	1
575 #define	SATA_RDWR_PMULT_PKT_TYPE_WRITE	2
576 
577 /*
578  * Hoplug functions vector structure (rev 1)
579  */
580 #define	SATA_TRAN_HOTPLUG_OPS_REV_1	1
581 
582 struct sata_tran_hotplug_ops {
583 	int	sata_tran_hotplug_ops_rev; /* version */
584 	int	(*sata_tran_port_activate)(dev_info_t  *, sata_device_t *);
585 	int	(*sata_tran_port_deactivate)(dev_info_t  *, sata_device_t *);
586 };
587 
588 typedef struct sata_tran_hotplug_ops sata_tran_hotplug_ops_t;
589 
590 
591 /*
592  * Power management functions vector structure (rev 1)
593  * The embedded function returns information about the controller's
594  * power level.
595  * Additional functions may be added in the future without changes to
596  * sata_tran structure.
597  */
598 #define	SATA_TRAN_PWRMGT_OPS_REV_1	1
599 
600 struct sata_tran_pwrmgt_ops {
601 	int	sata_tran_pwrmgt_ops_rev; /* version */
602 	int	(*sata_tran_get_pwr_level)(dev_info_t  *, sata_device_t *);
603 };
604 
605 typedef struct sata_tran_pwrmgt_ops sata_tran_pwrmgt_ops_t;
606 
607 
608 /*
609  * SATA port PHY Power Level
610  * These states correspond to the interface power management state as defined
611  * in Serial ATA spec.
612  */
613 #define	SATA_TRAN_PORTPWR_LEVEL1	1 /* Interface in active PM state */
614 #define	SATA_TRAN_PORTPWR_LEVEL2	2 /* Interface in PARTIAL PM state */
615 #define	SATA_TRAN_PORTPWR_LEVEL3	3 /* Interface in SLUMBER PM state */
616 
617 /*
618  * SATA HBA Tran structure (rev 1)
619  * Registered with SATA Framework
620  *
621  * dma_attr is a pointer to data (buffer) dma attibutes of the controller
622  * DMA engine.
623  *
624  * The qdepth field specifies number of commands that may be accepted by
625  * the controller. Value range 1-32. A value greater than 1 indicates that
626  * the controller supports queuing. Support for Native Command Queuing
627  * indicated by SATA_CTLF_NCQ flag also requires qdepth set to a value
628  * greater then 1.
629  *
630  */
631 #define	SATA_TRAN_HBA_REV_1	1
632 #define	SATA_TRAN_HBA_REV_2	2
633 #define	SATA_TRAN_HBA_REV_3	3
634 #define	SATA_TRAN_HBA_REV	SATA_TRAN_HBA_REV_3
635 
636 struct sata_hba_tran {
637 	int		sata_tran_hba_rev;	/* version */
638 	dev_info_t	*sata_tran_hba_dip;	/* Controler dev info */
639 	ddi_dma_attr_t	*sata_tran_hba_dma_attr; /* DMA attributes */
640 	int		sata_tran_hba_num_cports; /* Num of HBA device ports */
641 	uint16_t	sata_tran_hba_features_support; /* HBA features */
642 	uint16_t	sata_tran_hba_qdepth;	/* HBA-supported queue depth */
643 
644 	int		(*sata_tran_probe_port)(dev_info_t *, sata_device_t *);
645 	int		(*sata_tran_start)(dev_info_t *, sata_pkt_t *);
646 	int		(*sata_tran_abort)(dev_info_t *, sata_pkt_t *, int);
647 	int		(*sata_tran_reset_dport)(dev_info_t *,
648 					sata_device_t *);
649 	int		(*sata_tran_selftest)(dev_info_t *, sata_device_t *);
650 
651 						/* Hotplug vector */
652 	struct sata_tran_hotplug_ops *sata_tran_hotplug_ops;
653 
654 						/* Power mgt vector */
655 	struct sata_tran_pwrmgt_ops *sata_tran_pwrmgt_ops;
656 
657 	int		(*sata_tran_ioctl)(dev_info_t *, int, intptr_t);
658 };
659 
660 typedef struct sata_hba_tran sata_hba_tran_t;
661 
662 
663 /*
664  * Controller's features support flags (sata_tran_hba_features_support).
665  * Note: SATA_CTLF_NCQ indicates that SATA controller supports NCQ in addition
666  * to legacy queuing commands, indicated by SATA_CTLF_QCMD flag.
667  */
668 
669 #define	SATA_CTLF_ATAPI			0x001 /* ATAPI support */
670 #define	SATA_CTLF_PORT_MULTIPLIER	0x010 /* Port Multiplier suport */
671 #define	SATA_CTLF_HOTPLUG		0x020 /* Hotplug support */
672 #define	SATA_CTLF_ASN			0x040 /* Asynchronous Event Support */
673 #define	SATA_CTLF_QCMD			0x080 /* Queued commands support */
674 #define	SATA_CTLF_NCQ			0x100 /* NCQ support */
675 #define	SATA_CTLF_PMULT_FBS		0x200 /* FIS-based switching support */
676 
677 /*
678  * sata_tran_start() return values.
679  * When pkt is not accepted, the satapkt_reason has to be updated
680  * before function returns - it should reflect the same reason for not being
681  * executed as the return status of above functions.
682  * If pkt was accepted and executed synchronously,
683  * satapk_reason should indicate a completion status.
684  */
685 #define	SATA_TRAN_ACCEPTED		0 /* accepted */
686 #define	SATA_TRAN_QUEUE_FULL		1 /* not accepted, queue full */
687 #define	SATA_TRAN_PORT_ERROR		2 /* not accepted, port error */
688 #define	SATA_TRAN_CMD_UNSUPPORTED	3 /* not accepted, cmd not supported */
689 #define	SATA_TRAN_BUSY			4 /* not accepted, busy */
690 
691 
692 /*
693  * sata_tran_abort() abort type flag
694  */
695 #define	SATA_ABORT_PACKET		0
696 #define	SATA_ABORT_ALL_PACKETS		1
697 
698 
699 /*
700  * Events handled by SATA HBA Framework
701  * More then one event may be reported at the same time
702  *
703  * SATA_EVNT__DEVICE_ATTACHED
704  * HBA detected the presence of a device ( electrical connection with
705  * a device was detected ).
706  *
707  * SATA_EVNT_DEVICE_DETACHED
708  * HBA detected the detachment of a device (electrical connection with
709  * a device was broken)
710  *
711  * SATA_EVNT_LINK_LOST
712  * HBA lost link with an attached device
713  *
714  * SATA_EVNT_LINK_ESTABLISHED
715  * HBA established a link with an attached device
716  *
717  * SATA_EVNT_PORT_FAILED
718  * HBA has determined that the port failed and is unuseable
719  *
720  * SATA_EVENT_DEVICE_RESET
721  * SATA device was reset, causing loss of the device setting
722  *
723  * SATA_EVNT_PWR_LEVEL_CHANGED
724  * A port or entire SATA controller power level has changed
725  *
726  * SATA_EVNT_PMULT_LINK_CHANGED
727  * Port multiplier detect change on a link of its device port
728  *
729  */
730 #define	SATA_EVNT_DEVICE_ATTACHED	0x01
731 #define	SATA_EVNT_DEVICE_DETACHED	0x02
732 #define	SATA_EVNT_LINK_LOST		0x04
733 #define	SATA_EVNT_LINK_ESTABLISHED	0x08
734 #define	SATA_EVNT_PORT_FAILED		0x10
735 #define	SATA_EVNT_DEVICE_RESET		0x20
736 #define	SATA_EVNT_PWR_LEVEL_CHANGED	0x40
737 #define	SATA_EVNT_PMULT_LINK_CHANGED	0x80
738 
739 /*
740  * SATA Framework interface entry points
741  */
742 int	sata_hba_init(struct modlinkage *);
743 int	sata_hba_attach(dev_info_t *, sata_hba_tran_t *, ddi_attach_cmd_t);
744 int	sata_hba_detach(dev_info_t *, ddi_detach_cmd_t);
745 void	sata_hba_fini(struct modlinkage *);
746 void	sata_hba_event_notify(dev_info_t *, sata_device_t *, int);
747 sata_pkt_t *sata_get_error_retrieval_pkt(dev_info_t *, sata_device_t *, int);
748 void	sata_free_error_retrieval_pkt(sata_pkt_t *);
749 sata_pkt_t *sata_get_rdwr_pmult_pkt(dev_info_t *, sata_device_t *, uint16_t,
750     uint32_t, uint32_t);
751 void	sata_free_rdwr_pmult_pkt(sata_pkt_t *);
752 void	sata_register_pmult(dev_info_t *, sata_device_t *, sata_pmult_gscr_t *);
753 void	sata_free_dma_resources(sata_pkt_t *);
754 void	sata_split_model(char *, char **, char **);
755 
756 /*
757  * SATA trace ring buffer constants
758  */
759 #define	DMSG_RING_SIZE		0x100000	/* 1MB */
760 #define	DMSG_BUF_SIZE		256
761 
762 /*
763  * SATA trace ring buffer content
764  */
765 typedef struct sata_trace_dmsg {
766 	dev_info_t		*dip;
767 	timespec_t		timestamp;
768 	char			buf[DMSG_BUF_SIZE];
769 	struct sata_trace_dmsg	*next;
770 } sata_trace_dmsg_t;
771 
772 /*
773  * SATA trace ring buffer header
774  */
775 typedef struct sata_trace_rbuf {
776 	kmutex_t		lock;		/* lock to avoid clutter */
777 	int			looped;		/* completed ring */
778 	int			allocfailed;	/* dmsg mem alloc failed */
779 	size_t			size;		/* current size */
780 	size_t			maxsize;	/* max size */
781 	sata_trace_dmsg_t	*dmsgh;		/* messages head */
782 	sata_trace_dmsg_t	*dmsgp;		/* ptr to last message */
783 } sata_trace_rbuf_t;
784 
785 /*
786  * SATA trace ring buffer interfaces
787  */
788 void sata_trace_debug(dev_info_t *, const char *fmt, ...);
789 void sata_vtrace_debug(dev_info_t *, const char *fmt, va_list);
790 
791 #ifdef	__cplusplus
792 }
793 #endif
794 
795 #endif /* _SATA_HBA_H */
796