drivers/scsi/isci/core/scic_sds_request.h

   1 /*
   2  * This file is provided under a dual BSD/GPLv2 license.  When using or
   3  * redistributing this file, you may do so under either license.
   4  *
   5  * GPL LICENSE SUMMARY
   6  *
   7  * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of version 2 of the GNU General Public License as
  11  * published by the Free Software Foundation.
  12  *
  13  * This program is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA.
  21  * The full GNU General Public License is included in this distribution
  22  * in the file called LICENSE.GPL.
  23  *
  24  * BSD LICENSE
  25  *
  26  * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
  27  * All rights reserved.
  28  *
  29  * Redistribution and use in source and binary forms, with or without
  30  * modification, are permitted provided that the following conditions
  31  * are met:
  32  *
  33  *   * Redistributions of source code must retain the above copyright
  34  *     notice, this list of conditions and the following disclaimer.
  35  *   * Redistributions in binary form must reproduce the above copyright
  36  *     notice, this list of conditions and the following disclaimer in
  37  *     the documentation and/or other materials provided with the
  38  *     distribution.
  39  *   * Neither the name of Intel Corporation nor the names of its
  40  *     contributors may be used to endorse or promote products derived
  41  *     from this software without specific prior written permission.
  42  *
  43  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  44  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  45  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  46  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  47  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  48  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  49  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  50  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  51  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  52  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  53  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  54  */
  55
  56 #ifndef _SCIC_SDS_IO_REQUEST_H_
  57 #define _SCIC_SDS_IO_REQUEST_H_
  58
  59 /**
  60  * This file contains the structures, constants and prototypes for the
  61  *    SCIC_SDS_IO_REQUEST object.
  62  *
  63  *
  64  */
  65
  66 #include "scic_io_request.h"
  67 #include "sci_base_state_machine.h"
  68 #include "scu_task_context.h"
  69 #include "intel_sas.h"
  70
  71 struct scic_sds_controller;
  72 struct scic_sds_remote_device;
  73 struct scic_sds_io_request_state_handler;
  74
  75 /**
  76  * enum _scic_sds_io_request_started_task_mgmt_substates - This enumeration
  77  *    depicts all of the substates for a task management request to be
  78  *    performed in the STARTED super-state.
  79  *
  80  *
  81  */
  82 enum scic_sds_raw_request_started_task_mgmt_substates {
  83         /**
  84          * The AWAIT_TC_COMPLETION sub-state indicates that the started raw
  85          * task management request is waiting for the transmission of the
  86          * initial frame (i.e. command, task, etc.).
  87          */
  88         SCIC_SDS_IO_REQUEST_STARTED_TASK_MGMT_SUBSTATE_AWAIT_TC_COMPLETION,
  89
  90         /**
  91          * This sub-state indicates that the started task management request
  92          * is waiting for the reception of an unsolicited frame
  93          * (i.e. response IU).
  94          */
  95         SCIC_SDS_IO_REQUEST_STARTED_TASK_MGMT_SUBSTATE_AWAIT_TC_RESPONSE,
  96 };
  97
  98
  99 /**
 100  * enum _scic_sds_smp_request_started_substates - This enumeration depicts all
 101  *    of the substates for a SMP request to be performed in the STARTED
 102  *    super-state.
 103  *
 104  *
 105  */
 106 enum scic_sds_smp_request_started_substates {
 107         /**
 108          * This sub-state indicates that the started task management request
 109          * is waiting for the reception of an unsolicited frame
 110          * (i.e. response IU).
 111          */
 112         SCIC_SDS_SMP_REQUEST_STARTED_SUBSTATE_AWAIT_RESPONSE,
 113
 114         /**
 115          * The AWAIT_TC_COMPLETION sub-state indicates that the started SMP request is
 116          * waiting for the transmission of the initial frame (i.e. command, task, etc.).
 117          */
 118         SCIC_SDS_SMP_REQUEST_STARTED_SUBSTATE_AWAIT_TC_COMPLETION,
 119 };
 120
 121 struct isci_request;
 122 /**
 123  * struct scic_sds_request - This structure contains or references all of
 124  *    the data necessary to process a task management or normal IO request.
 125  *
 126  *
 127  */
 128 struct scic_sds_request {
 129         /**
 130          * The field specifies that the peer object for the request object.
 131          */
 132         struct isci_request *ireq;
 133
 134         /**
 135          * This field contains the information for the base request state machine.
 136          */
 137         struct sci_base_state_machine state_machine;
 138
 139         void *user_request;
 140
 141         /**
 142          * This field simply points to the controller to which this IO request
 143          * is associated.
 144          */
 145         struct scic_sds_controller *owning_controller;
 146
 147         /**
 148          * This field simply points to the remote device to which this IO request
 149          * is associated.
 150          */
 151         struct scic_sds_remote_device *target_device;
 152
 153         /**
 154          * This field is utilized to determine if the SCI user is managing
 155          * the IO tag for this request or if the core is managing it.
 156          */
 157         bool was_tag_assigned_by_user;
 158
 159         /**
 160          * This field indicates the IO tag for this request.  The IO tag is
 161          * comprised of the task_index and a sequence count. The sequence count
 162          * is utilized to help identify tasks from one life to another.
 163          */
 164         u16 io_tag;
 165
 166         /**
 167          * This field specifies the protocol being utilized for this
 168          * IO request.
 169          */
 170         SCIC_TRANSPORT_PROTOCOL protocol;
 171
 172         /**
 173          * This field indicates the completion status taken from the SCUs
 174          * completion code.  It indicates the completion result for the SCU hardware.
 175          */
 176         u32 scu_status;
 177
 178         /**
 179          * This field indicates the completion status returned to the SCI user.  It
 180          * indicates the users view of the io request completion.
 181          */
 182         u32 sci_status;
 183
 184         /**
 185          * This field contains the value to be utilized when posting (e.g. Post_TC,
 186          * Post_TC_Abort) this request to the silicon.
 187          */
 188         u32 post_context;
 189
 190         void *command_buffer;
 191         void *response_buffer;
 192         struct scu_task_context *task_context_buffer;
 193         struct scu_sgl_element_pair *sgl_element_pair_buffer;
 194
 195         /**
 196          * This field indicates if this request is a task management request or
 197          * normal IO request.
 198          */
 199         bool is_task_management_request;
 200
 201         /**
 202          * This field indicates that this request contains an initialized started
 203          * substate machine.
 204          */
 205         bool has_started_substate_machine;
 206
 207         /**
 208          * This field is a pointer to the stored rx frame data.  It is used in STP
 209          * internal requests and SMP response frames.  If this field is non-NULL the
 210          * saved frame must be released on IO request completion.
 211          *
 212          * @todo In the future do we want to keep a list of RX frame buffers?
 213          */
 214         u32 saved_rx_frame_index;
 215
 216         /**
 217          * This field specifies the data necessary to manage the sub-state
 218          * machine executed while in the SCI_BASE_REQUEST_STATE_STARTED state.
 219          */
 220         struct sci_base_state_machine started_substate_machine;
 221
 222         /**
 223          * This field specifies the current state handlers in place for this
 224          * IO Request object.  This field is updated each time the request
 225          * changes state.
 226          */
 227         const struct scic_sds_io_request_state_handler *state_handlers;
 228
 229         /**
 230          * This field in the recorded device sequence for the io request.  This is
 231          * recorded during the build operation and is compared in the start
 232          * operation.  If the sequence is different then there was a change of
 233          * devices from the build to start operations.
 234          */
 235         u8 device_sequence;
 236
 237 };
 238
 239 /**
 240  * enum sci_base_request_states - This enumeration depicts all the states for
 241  *    the common request state machine.
 242  *
 243  *
 244  */
 245 enum sci_base_request_states {
 246         /**
 247          * Simply the initial state for the base request state machine.
 248          */
 249         SCI_BASE_REQUEST_STATE_INITIAL,
 250
 251         /**
 252          * This state indicates that the request has been constructed. This state
 253          * is entered from the INITIAL state.
 254          */
 255         SCI_BASE_REQUEST_STATE_CONSTRUCTED,
 256
 257         /**
 258          * This state indicates that the request has been started. This state is
 259          * entered from the CONSTRUCTED state.
 260          */
 261         SCI_BASE_REQUEST_STATE_STARTED,
 262
 263         /**
 264          * This state indicates that the request has completed.
 265          * This state is entered from the STARTED state. This state is entered from
 266          * the ABORTING state.
 267          */
 268         SCI_BASE_REQUEST_STATE_COMPLETED,
 269
 270         /**
 271          * This state indicates that the request is in the process of being
 272          * terminated/aborted.
 273          * This state is entered from the CONSTRUCTED state.
 274          * This state is entered from the STARTED state.
 275          */
 276         SCI_BASE_REQUEST_STATE_ABORTING,
 277
 278         /**
 279          * Simply the final state for the base request state machine.
 280          */
 281         SCI_BASE_REQUEST_STATE_FINAL,
 282 };
 283
 284 typedef enum sci_status (*scic_sds_io_request_handler_t)
 285                                 (struct scic_sds_request *request);
 286 typedef enum sci_status (*scic_sds_io_request_frame_handler_t)
 287                                 (struct scic_sds_request *req, u32 frame);
 288 typedef enum sci_status (*scic_sds_io_request_event_handler_t)
 289                                 (struct scic_sds_request *req, u32 event);
 290 typedef enum sci_status (*scic_sds_io_request_task_completion_handler_t)
 291                                 (struct scic_sds_request *req, u32 completion_code);
 292
 293 /**
 294  * struct scic_sds_io_request_state_handler - This is the SDS core definition
 295  *    of the state handlers.
 296  *
 297  *
 298  */
 299 struct scic_sds_io_request_state_handler {
 300         /**
 301          * The start_handler specifies the method invoked when a user attempts to
 302          * start a request.
 303          */
 304         scic_sds_io_request_handler_t start_handler;
 305
 306         /**
 307          * The abort_handler specifies the method invoked when a user attempts to
 308          * abort a request.
 309          */
 310         scic_sds_io_request_handler_t abort_handler;
 311
 312         /**
 313          * The complete_handler specifies the method invoked when a user attempts to
 314          * complete a request.
 315          */
 316         scic_sds_io_request_handler_t complete_handler;
 317
 318         scic_sds_io_request_task_completion_handler_t tc_completion_handler;
 319         scic_sds_io_request_event_handler_t event_handler;
 320         scic_sds_io_request_frame_handler_t frame_handler;
 321
 322 };
 323
 324 extern const struct sci_base_state scic_sds_io_request_started_task_mgmt_substate_table[];
 325
 326 /**
 327  *
 328  *
 329  * This macro returns the maximum number of SGL element paris that we will
 330  * support in a single IO request.
 331  */
 332 #define SCU_MAX_SGL_ELEMENT_PAIRS ((SCU_IO_REQUEST_SGE_COUNT + 1) / 2)
 333
 334 /**
 335  * scic_sds_request_get_controller() -
 336  *
 337  * This macro will return the controller for this io request object
 338  */
 339 #define scic_sds_request_get_controller(sci_req) \
 340         ((sci_req)->owning_controller)
 341
 342 /**
 343  * scic_sds_request_get_device() -
 344  *
 345  * This macro will return the device for this io request object
 346  */
 347 #define scic_sds_request_get_device(sci_req) \
 348         ((sci_req)->target_device)
 349
 350 /**
 351  * scic_sds_request_get_port() -
 352  *
 353  * This macro will return the port for this io request object
 354  */
 355 #define scic_sds_request_get_port(sci_req)      \
 356         scic_sds_remote_device_get_port(scic_sds_request_get_device(sci_req))
 357
 358 /**
 359  * scic_sds_request_get_post_context() -
 360  *
 361  * This macro returns the constructed post context result for the io request.
 362  */
 363 #define scic_sds_request_get_post_context(sci_req)      \
 364         ((sci_req)->post_context)
 365
 366 /**
 367  * scic_sds_request_get_task_context() -
 368  *
 369  * This is a helper macro to return the os handle for this request object.
 370  */
 371 #define scic_sds_request_get_task_context(request) \
 372         ((request)->task_context_buffer)
 373
 374 /**
 375  * scic_sds_request_set_status() -
 376  *
 377  * This macro will set the scu hardware status and sci request completion
 378  * status for an io request.
 379  */
 380 #define scic_sds_request_set_status(request, scu_status_code, sci_status_code) \
 381         { \
 382                 (request)->scu_status = (scu_status_code); \
 383                 (request)->sci_status = (sci_status_code); \
 384         }
 385
 386 #define scic_sds_request_complete(a_request) \
 387         ((a_request)->state_handlers->complete_handler(a_request))
 388
 389
 390 extern enum sci_status
 391 scic_sds_io_request_tc_completion(struct scic_sds_request *request, u32 completion_code);
 392
 393 /**
 394  * SCU_SGL_ZERO() -
 395  *
 396  * This macro zeros the hardware SGL element data
 397  */
 398 #define SCU_SGL_ZERO(scu_sge) \
 399         { \
 400                 (scu_sge).length = 0; \
 401                 (scu_sge).address_lower = 0; \
 402                 (scu_sge).address_upper = 0; \
 403                 (scu_sge).address_modifier = 0; \
 404         }
 405
 406 /**
 407  * SCU_SGL_COPY() -
 408  *
 409  * This macro copys the SGL Element data from the host os to the hardware SGL
 410  * elment data
 411  */
 412 #define SCU_SGL_COPY(scu_sge, os_sge) \
 413         { \
 414                 (scu_sge).length = sg_dma_len(sg); \
 415                 (scu_sge).address_upper = \
 416                         upper_32_bits(sg_dma_address(sg)); \
 417                 (scu_sge).address_lower = \
 418                         lower_32_bits(sg_dma_address(sg)); \
 419                 (scu_sge).address_modifier = 0; \
 420         }
 421
 422 /**
 423  * scic_sds_request_get_user_request() -
 424  *
 425  * This is a helper macro to return the os handle for this request object.
 426  */
 427 #define scic_sds_request_get_user_request(request) \
 428         ((request)->user_request)
 429
 430 /*
 431  * *****************************************************************************
 432  * * CORE REQUEST PROTOTYPES
 433  * ***************************************************************************** */
 434
 435 void scic_sds_request_build_sgl(
 436         struct scic_sds_request *sci_req);
 437
 438
 439
 440 void scic_sds_stp_request_assign_buffers(
 441         struct scic_sds_request *sci_req);
 442
 443 void scic_sds_smp_request_assign_buffers(
 444         struct scic_sds_request *sci_req);
 445
 446 /* --------------------------------------------------------------------------- */
 447
 448 enum sci_status scic_sds_request_start(
 449         struct scic_sds_request *sci_req);
 450
 451 enum sci_status scic_sds_io_request_terminate(
 452         struct scic_sds_request *sci_req);
 453
 454 enum sci_status scic_sds_io_request_complete(
 455         struct scic_sds_request *sci_req);
 456
 457 void scic_sds_io_request_copy_response(
 458         struct scic_sds_request *sci_req);
 459
 460 enum sci_status scic_sds_io_request_event_handler(
 461         struct scic_sds_request *sci_req,
 462         u32 event_code);
 463
 464 enum sci_status scic_sds_io_request_frame_handler(
 465         struct scic_sds_request *sci_req,
 466         u32 frame_index);
 467
 468
 469 enum sci_status scic_sds_task_request_terminate(
 470         struct scic_sds_request *sci_req);
 471
 472 /*
 473  * *****************************************************************************
 474  * * STARTED STATE HANDLERS
 475  * ***************************************************************************** */
 476
 477 enum sci_status scic_sds_request_started_state_abort_handler(
 478         struct scic_sds_request *sci_req);
 479
 480 enum sci_status scic_sds_request_started_state_tc_completion_handler(
 481         struct scic_sds_request *sci_req,
 482         u32 completion_code);
 483
 484 #endif /* _SCIC_SDS_IO_REQUEST_H_ */