1/*-
2 * SPDX-License-Identifier: BSD-2-Clause OR GPL-2.0
3 *
4 * This file is provided under a dual BSD/GPLv2 license.  When using or
5 * redistributing this file, you may do so under either license.
6 *
7 * GPL LICENSE SUMMARY
8 *
9 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
10 *
11 * This program is free software; you can redistribute it and/or modify
12 * it under the terms of version 2 of the GNU General Public License as
13 * published by the Free Software Foundation.
14 *
15 * This program is distributed in the hope that it will be useful, but
16 * WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
18 * General Public License for more details.
19 *
20 * You should have received a copy of the GNU General Public License
21 * along with this program; if not, write to the Free Software
22 * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA.
23 * The full GNU General Public License is included in this distribution
24 * in the file called LICENSE.GPL.
25 *
26 * BSD LICENSE
27 *
28 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
29 * All rights reserved.
30 *
31 * Redistribution and use in source and binary forms, with or without
32 * modification, are permitted provided that the following conditions
33 * are met:
34 *
35 *   * Redistributions of source code must retain the above copyright
36 *     notice, this list of conditions and the following disclaimer.
37 *   * Redistributions in binary form must reproduce the above copyright
38 *     notice, this list of conditions and the following disclaimer in
39 *     the documentation and/or other materials provided with the
40 *     distribution.
41 *
42 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
43 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
44 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
45 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
46 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
47 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
48 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
49 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
50 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
51 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
52 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
53 *
54 * $FreeBSD$
55 */
56#ifndef _SCIC_SDS_PHY_H_
57#define _SCIC_SDS_PHY_H_
58
59/**
60 * @file
61 *
62 * @brief This file contains the structures, constants and prototypes for the
63 *        SCIC_SDS_PHY object.
64 */
65
66#ifdef __cplusplus
67extern "C" {
68#endif // __cplusplus
69
70#include <dev/isci/scil/intel_sata.h>
71#include <dev/isci/scil/intel_sas.h>
72#include <dev/isci/scil/sci_base_phy.h>
73#include <dev/isci/scil/scu_registers.h>
74#include <dev/isci/scil/scu_event_codes.h>
75
76/**
77 * This is the timeout value for the SATA phy to wait for a SIGNATURE FIS
78 * before restarting the starting state machine.  Technically, the old
79 * parallel ATA specification required up to 30 seconds for a device to
80 * issue its signature FIS as a result of a soft reset.  Now we see that
81 * devices respond generally within 15 seconds, but we'll use 25 for now.
82 */
83#define SCIC_SDS_SIGNATURE_FIS_TIMEOUT    25000
84
85/**
86 * This is the timeout for the SATA OOB/SN because the hardware does not
87 * recognize a hot plug after OOB signal but before the SN signals.  We
88 * need to make sure after a hotplug timeout if we have not received the
89 * speed event notification from the hardware that we restart the hardware
90 * OOB state machine.
91 */
92#define SCIC_SDS_SATA_LINK_TRAINING_TIMEOUT  250
93
94/**
95 * @enum SCIC_SDS_PHY_STARTING_SUBSTATES
96 */
97enum SCIC_SDS_PHY_STARTING_SUBSTATES
98{
99   /**
100    * Initial state
101    */
102   SCIC_SDS_PHY_STARTING_SUBSTATE_INITIAL,
103
104   /**
105    * Wait state for the hardware OSSP event type notification
106    */
107   SCIC_SDS_PHY_STARTING_SUBSTATE_AWAIT_OSSP_EN,
108
109   /**
110    * Wait state for the PHY speed notification
111    */
112   SCIC_SDS_PHY_STARTING_SUBSTATE_AWAIT_SAS_SPEED_EN,
113
114   /**
115    * Wait state for the IAF Unsolicited frame notification
116    */
117   SCIC_SDS_PHY_STARTING_SUBSTATE_AWAIT_IAF_UF,
118
119   /**
120    * Wait state for the request to consume power
121    */
122   SCIC_SDS_PHY_STARTING_SUBSTATE_AWAIT_SAS_POWER,
123
124   /**
125    * Wait state for request to consume power
126    */
127   SCIC_SDS_PHY_STARTING_SUBSTATE_AWAIT_SATA_POWER,
128
129   /**
130    * Wait state for the SATA PHY notification
131    */
132   SCIC_SDS_PHY_STARTING_SUBSTATE_AWAIT_SATA_PHY_EN,
133
134   /**
135    * Wait for the SATA PHY speed notification
136    */
137   SCIC_SDS_PHY_STARTING_SUBSTATE_AWAIT_SATA_SPEED_EN,
138
139   /**
140    * Wait state for the SIGNATURE FIS unsolicited frame notification
141    */
142   SCIC_SDS_PHY_STARTING_SUBSTATE_AWAIT_SIG_FIS_UF,
143
144   /**
145    * Exit state for this state machine
146    */
147   SCIC_SDS_PHY_STARTING_SUBSTATE_FINAL,
148
149   /**
150    * Maximum number of substates for the STARTING state machine
151    */
152   SCIC_SDS_PHY_STARTING_MAX_SUBSTATES
153};
154
155struct SCIC_SDS_PORT;
156struct SCIC_SDS_CONTROLLER;
157
158#ifdef SCIC_DEBUG_ENABLED
159#define MAX_STATE_TRANSITION_RECORD    (256)
160
161/**
162 * Debug code to record the state transitions for the phy object
163 */
164typedef struct SCIC_SDS_PHY_STATE_RECORD
165{
166   SCI_BASE_OBSERVER_T  base_state_observer;
167   SCI_BASE_OBSERVER_T  starting_state_observer;
168
169   U16 index;
170
171   U32 state_transition_table[MAX_STATE_TRANSITION_RECORD];
172
173} SCIC_SDS_PHY_STATE_RECORD_T;
174#endif // SCIC_DEBUG_ENABLED
175
176/**
177 * @enum
178 *
179 * @brief This enumeration provides a named phy type for the state machine
180 */
181enum SCIC_SDS_PHY_PROTOCOL
182{
183   /**
184    * This is an unknown phy type since there is either nothing on the other
185    * end or we have not detected the phy type as yet.
186    */
187   SCIC_SDS_PHY_PROTOCOL_UNKNOWN,
188
189   /**
190    * This is a SAS PHY
191    */
192   SCIC_SDS_PHY_PROTOCOL_SAS,
193
194   /**
195    * This is a SATA PHY
196    */
197   SCIC_SDS_PHY_PROTOCOL_SATA,
198
199   SCIC_SDS_MAX_PHY_PROTOCOLS
200};
201
202/**
203 * @struct SCIC_SDS_PHY
204 *
205 * @brief This structure  contains or references all of the data necessary to
206 *        represent the core phy object and SCU hardware protocol engine.
207 */
208typedef struct SCIC_SDS_PHY
209{
210   SCI_BASE_PHY_T parent;
211
212   /**
213    * This field specifies the port object that owns/contains this phy.
214    */
215   struct SCIC_SDS_PORT * owning_port;
216
217   /**
218    * This field indicates whether the phy supports 1.5 Gb/s, 3.0 Gb/s,
219    * or 6.0 Gb/s operation.
220    */
221   SCI_SAS_LINK_RATE max_negotiated_speed;
222
223   /**
224    * This member specifies the protocol being utilized on this phy.  This
225    * field contains a legitamite value once the PHY has link trained with
226    * a remote phy.
227    */
228   enum SCIC_SDS_PHY_PROTOCOL protocol;
229
230   /**
231    * This field specifies the index with which this phy is associated (0-3).
232    */
233   U8 phy_index;
234
235   /**
236    * This member indicates if this particular PHY has received a BCN while
237    * it had no port assignement.  This BCN will be reported once the phy is
238    * assigned to a port.
239    */
240   BOOL bcn_received_while_port_unassigned;
241
242   /**
243    * This field indicates if this PHY is currently in the process of
244    * link training (i.e. it has started OOB, but has yet to perform
245    * IAF exchange/Signature FIS reception).
246    */
247   BOOL is_in_link_training;
248
249   union
250   {
251      struct
252      {
253         SCI_SAS_IDENTIFY_ADDRESS_FRAME_T identify_address_frame_buffer;
254
255      } sas;
256
257      struct
258      {
259         SATA_FIS_REG_D2H_T signature_fis_buffer;
260
261      } sata;
262
263   } phy_type;
264
265   /**
266    * This field contains a reference to the timer utilized in detecting
267    * when a signature FIS timeout has occurred.  The signature FIS is the
268    * first FIS sent by an attached SATA device after OOB/SN.
269    */
270   void * sata_timeout_timer;
271
272   struct SCIC_SDS_PHY_STATE_HANDLER *state_handlers;
273
274   SCI_BASE_STATE_MACHINE_T starting_substate_machine;
275
276   #ifdef SCI_LOGGING
277   SCI_BASE_STATE_MACHINE_LOGGER_T starting_substate_machine_logger;
278   #endif
279
280   #ifdef SCIC_DEBUG_ENABLED
281   SCIC_SDS_PHY_STATE_RECORD_T state_record;
282   #endif // SCIC_DEBUG_ENABLED
283
284   /**
285    * This field tracks how many errors of each type have been detected since
286    *  the last controller reset or counter clear.  Note that these are only
287    *  for the error types that our driver needs to count manually.  See
288    *  SCU_ERR_CNT_* values defined in scu_event_codes.h.
289    */
290   U32   error_counter[SCU_ERR_CNT_MAX_INDEX];
291
292   /**
293    * This field is the pointer to the transport layer register for the SCU
294    * hardware.
295    */
296   SCU_TRANSPORT_LAYER_REGISTERS_T *transport_layer_registers;
297
298   /**
299    * This field points to the link layer register set within the SCU.
300    */
301   SCU_LINK_LAYER_REGISTERS_T *link_layer_registers;
302
303} SCIC_SDS_PHY_T;
304
305
306typedef SCI_STATUS (*SCIC_SDS_PHY_EVENT_HANDLER_T)(SCIC_SDS_PHY_T *, U32);
307typedef SCI_STATUS (*SCIC_SDS_PHY_FRAME_HANDLER_T)(SCIC_SDS_PHY_T *, U32);
308typedef SCI_STATUS (*SCIC_SDS_PHY_POWER_HANDLER_T)(SCIC_SDS_PHY_T *);
309
310/**
311 * @struct SCIC_SDS_PHY_STATE_HANDLER
312 */
313typedef struct SCIC_SDS_PHY_STATE_HANDLER
314{
315   /**
316    * This is the SCI_BASE_PHY object state handlers.
317    */
318   SCI_BASE_PHY_STATE_HANDLER_T parent;
319
320   /**
321    * The state handler for unsolicited frames received from the SCU hardware.
322    */
323   SCIC_SDS_PHY_FRAME_HANDLER_T frame_handler;
324
325   /**
326    * The state handler for events received from the SCU hardware.
327    */
328   SCIC_SDS_PHY_EVENT_HANDLER_T event_handler;
329
330   /**
331    * The state handler for staggered spinup.
332    */
333   SCIC_SDS_PHY_POWER_HANDLER_T consume_power_handler;
334
335} SCIC_SDS_PHY_STATE_HANDLER_T;
336
337extern SCIC_SDS_PHY_STATE_HANDLER_T scic_sds_phy_state_handler_table[];
338extern SCI_BASE_STATE_T scic_sds_phy_state_table[];
339extern SCI_BASE_STATE_T scic_sds_phy_starting_substates[];
340extern SCIC_SDS_PHY_STATE_HANDLER_T
341       scic_sds_phy_starting_substate_handler_table[];
342
343
344/**
345 * This macro returns the phy index for the specified phy
346 */
347#define scic_sds_phy_get_index(phy) \
348   ((phy)->phy_index)
349
350/**
351 * @brief This macro returns the controller for this phy
352 */
353#define scic_sds_phy_get_controller(phy) \
354   (scic_sds_port_get_controller((phy)->owning_port))
355
356/**
357 * @brief This macro returns the state machine for the base phy
358 */
359#define scic_sds_phy_get_base_state_machine(phy) \
360   (&(phy)->parent.state_machine)
361
362/**
363 * @brief This macro returns the starting substate machine for
364 *        this phy
365 */
366#define scic_sds_phy_get_starting_substate_machine(phy) \
367   (&(phy)->starting_substate_machine)
368
369/**
370 * @brief This macro sets the state handlers for this phy object
371 */
372#define scic_sds_phy_set_state_handlers(phy, handlers) \
373   ((phy)->state_handlers = (handlers))
374
375/**
376 * This macro set the base state handlers for the phy object.
377 */
378#define scic_sds_phy_set_base_state_handlers(phy, state_id) \
379   scic_sds_phy_set_state_handlers( \
380      (phy), \
381      &scic_sds_phy_state_handler_table[(state_id)] \
382   )
383
384/**
385 * This macro returns TRUE if the current base state for this phy is
386 * SCI_BASE_PHY_STATE_READY
387 */
388#define scic_sds_phy_is_ready(phy) \
389   ( \
390         SCI_BASE_PHY_STATE_READY \
391      == sci_base_state_machine_get_state( \
392            scic_sds_phy_get_base_state_machine(phy) \
393         ) \
394   )
395
396// ---------------------------------------------------------------------------
397
398U32 scic_sds_phy_get_object_size(void);
399
400U32 scic_sds_phy_get_min_timer_count(void);
401
402U32 scic_sds_phy_get_max_timer_count(void);
403
404// ---------------------------------------------------------------------------
405
406void scic_sds_phy_construct(
407   struct SCIC_SDS_PHY  *this_phy,
408   struct SCIC_SDS_PORT *owning_port,
409   U8                    phy_index
410);
411
412SCI_PORT_HANDLE_T scic_sds_phy_get_port(
413   SCIC_SDS_PHY_T *this_phy
414);
415
416void scic_sds_phy_set_port(
417   struct SCIC_SDS_PHY  *this_phy,
418   struct SCIC_SDS_PORT *owning_port
419);
420
421SCI_STATUS scic_sds_phy_initialize(
422   SCIC_SDS_PHY_T             *this_phy,
423   void                       *transport_layer_registers,
424   SCU_LINK_LAYER_REGISTERS_T *link_layer_registers
425);
426
427SCI_STATUS scic_sds_phy_reset(
428   SCIC_SDS_PHY_T * this_phy
429);
430
431void scic_sds_phy_sata_timeout(
432   SCI_OBJECT_HANDLE_T cookie
433);
434
435// ---------------------------------------------------------------------------
436
437void scic_sds_phy_suspend(
438   struct SCIC_SDS_PHY  *this_phy
439);
440
441void scic_sds_phy_resume(
442   struct SCIC_SDS_PHY  *this_phy
443);
444
445void scic_sds_phy_setup_transport(
446   struct SCIC_SDS_PHY * this_phy,
447   U32                   device_id
448);
449
450// ---------------------------------------------------------------------------
451
452SCI_STATUS scic_sds_phy_event_handler(
453   SCIC_SDS_PHY_T *this_phy,
454   U32 event_code
455);
456
457SCI_STATUS scic_sds_phy_frame_handler(
458   SCIC_SDS_PHY_T *this_phy,
459   U32 frame_index
460);
461
462SCI_STATUS scic_sds_phy_consume_power_handler(
463   SCIC_SDS_PHY_T *this_phy
464);
465
466void scic_sds_phy_get_sas_address(
467   SCIC_SDS_PHY_T    *this_phy,
468   SCI_SAS_ADDRESS_T *sas_address
469);
470
471void scic_sds_phy_get_attached_sas_address(
472   SCIC_SDS_PHY_T    *this_phy,
473   SCI_SAS_ADDRESS_T *sas_address
474);
475
476void scic_sds_phy_get_protocols(
477   SCIC_SDS_PHY_T *this_phy,
478   SCI_SAS_IDENTIFY_ADDRESS_FRAME_PROTOCOLS_T * protocols
479);
480
481void scic_sds_phy_get_attached_phy_protocols(
482   SCIC_SDS_PHY_T *this_phy,
483   SCI_SAS_IDENTIFY_ADDRESS_FRAME_PROTOCOLS_T * protocols
484);
485
486//****************************************************************************-
487//* SCIC SDS PHY Handler Methods
488//****************************************************************************-
489
490SCI_STATUS scic_sds_phy_default_start_handler(
491   SCI_BASE_PHY_T *phy
492);
493
494SCI_STATUS scic_sds_phy_default_stop_handler(
495   SCI_BASE_PHY_T *phy
496);
497
498SCI_STATUS scic_sds_phy_default_reset_handler(
499   SCI_BASE_PHY_T * phy
500);
501
502SCI_STATUS scic_sds_phy_default_destroy_handler(
503   SCI_BASE_PHY_T *phy
504);
505
506SCI_STATUS scic_sds_phy_default_frame_handler(
507   SCIC_SDS_PHY_T *phy,
508   U32 frame_index
509);
510
511SCI_STATUS scic_sds_phy_default_event_handler(
512   SCIC_SDS_PHY_T *phy,
513   U32 evnet_code
514);
515
516SCI_STATUS scic_sds_phy_default_consume_power_handler(
517   SCIC_SDS_PHY_T *phy
518);
519
520void scic_sds_phy_release_resource(
521   struct SCIC_SDS_CONTROLLER * controller,
522   struct SCIC_SDS_PHY        * phy
523);
524
525void scic_sds_phy_restart_starting_state(
526   struct SCIC_SDS_PHY        * this_phy
527);
528
529#ifdef __cplusplus
530}
531#endif // __cplusplus
532
533#endif // _SCIC_SDS_PHY_H_
534