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.
7 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
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.
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.
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.
26 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
27 * All rights reserved.
29 * Redistribution and use in source and binary forms, with or without
30 * modification, are permitted provided that the following conditions
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
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.
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.
56 #ifndef _SCIC_SDS_IO_REQUEST_H_
57 #define _SCIC_SDS_IO_REQUEST_H_
60 * This file contains the structures, constants and prototypes for the
61 * SCIC_SDS_IO_REQUEST object.
66 #include "scic_io_request.h"
68 #include "sci_base_request.h"
69 #include "scu_task_context.h"
70 #include "intel_sas.h"
72 struct scic_sds_controller;
73 struct scic_sds_remote_device;
74 struct scic_sds_io_request_state_handler;
77 * enum _SCIC_SDS_IO_REQUEST_STARTED_TASK_MGMT_SUBSTATES - This enumeration
78 * depicts all of the substates for a task management request to be
79 * performed in the STARTED super-state.
83 enum scic_sds_raw_request_started_task_mgmt_substates {
85 * The AWAIT_TC_COMPLETION sub-state indicates that the started raw
86 * task management request is waiting for the transmission of the
87 * initial frame (i.e. command, task, etc.).
89 SCIC_SDS_IO_REQUEST_STARTED_TASK_MGMT_SUBSTATE_AWAIT_TC_COMPLETION,
92 * This sub-state indicates that the started task management request
93 * is waiting for the reception of an unsolicited frame
96 SCIC_SDS_IO_REQUEST_STARTED_TASK_MGMT_SUBSTATE_AWAIT_TC_RESPONSE,
101 * enum _SCIC_SDS_SMP_REQUEST_STARTED_SUBSTATES - This enumeration depicts all
102 * of the substates for a SMP request to be performed in the STARTED
107 enum scic_sds_smp_request_started_substates {
109 * This sub-state indicates that the started task management request
110 * is waiting for the reception of an unsolicited frame
111 * (i.e. response IU).
113 SCIC_SDS_SMP_REQUEST_STARTED_SUBSTATE_AWAIT_RESPONSE,
116 * The AWAIT_TC_COMPLETION sub-state indicates that the started SMP request is
117 * waiting for the transmission of the initial frame (i.e. command, task, etc.).
119 SCIC_SDS_SMP_REQUEST_STARTED_SUBSTATE_AWAIT_TC_COMPLETION,
123 * struct SCIC_SDS_IO_REQUEST - This structure contains or references all of
124 * the data necessary to process a task management or normal IO request.
128 struct scic_sds_request {
130 * This field indictes the parent object of the request.
132 struct sci_base_request parent;
137 * This field simply points to the controller to which this IO request
140 struct scic_sds_controller *owning_controller;
143 * This field simply points to the remote device to which this IO request
146 struct scic_sds_remote_device *target_device;
149 * This field is utilized to determine if the SCI user is managing
150 * the IO tag for this request or if the core is managing it.
152 bool was_tag_assigned_by_user;
155 * This field indicates the IO tag for this request. The IO tag is
156 * comprised of the task_index and a sequence count. The sequence count
157 * is utilized to help identify tasks from one life to another.
162 * This field specifies the protocol being utilized for this
165 SCIC_TRANSPORT_PROTOCOL protocol;
168 * This field indicates the completion status taken from the SCUs
169 * completion code. It indicates the completion result for the SCU hardware.
174 * This field indicates the completion status returned to the SCI user. It
175 * indicates the users view of the io request completion.
180 * This field contains the value to be utilized when posting (e.g. Post_TC,
181 * Post_TC_Abort) this request to the silicon.
185 void *command_buffer;
186 void *response_buffer;
187 struct scu_task_context *task_context_buffer;
188 struct scu_sgl_element_pair *sgl_element_pair_buffer;
191 * This field indicates if this request is a task management request or
194 bool is_task_management_request;
197 * This field indicates that this request contains an initialized started
200 bool has_started_substate_machine;
203 * This field is a pointer to the stored rx frame data. It is used in STP
204 * internal requests and SMP response frames. If this field is non-NULL the
205 * saved frame must be released on IO request completion.
207 * @todo In the future do we want to keep a list of RX frame buffers?
209 u32 saved_rx_frame_index;
212 * This field specifies the data necessary to manage the sub-state
213 * machine executed while in the SCI_BASE_REQUEST_STATE_STARTED state.
215 struct sci_base_state_machine started_substate_machine;
218 * This field specifies the current state handlers in place for this
219 * IO Request object. This field is updated each time the request
222 const struct scic_sds_io_request_state_handler *state_handlers;
225 * This field in the recorded device sequence for the io request. This is
226 * recorded during the build operation and is compared in the start
227 * operation. If the sequence is different then there was a change of
228 * devices from the build to start operations.
235 typedef enum sci_status
236 (*scic_sds_io_request_frame_handler_t)(struct scic_sds_request *req, u32 frame);
238 typedef enum sci_status
239 (*scic_sds_io_request_event_handler_t)(struct scic_sds_request *req, u32 event);
241 typedef enum sci_status
242 (*scic_sds_io_request_task_completion_handler_t)(struct scic_sds_request *req, u32 completion_code);
245 * struct scic_sds_io_request_state_handler - This is the SDS core definition
246 * of the state handlers.
250 struct scic_sds_io_request_state_handler {
251 struct sci_base_request_state_handler parent;
253 scic_sds_io_request_task_completion_handler_t tc_completion_handler;
254 scic_sds_io_request_event_handler_t event_handler;
255 scic_sds_io_request_frame_handler_t frame_handler;
259 extern const struct sci_base_state scic_sds_request_state_table[];
260 extern const struct scic_sds_io_request_state_handler scic_sds_request_state_handler_table[];
262 extern const struct sci_base_state scic_sds_io_request_started_task_mgmt_substate_table[];
263 extern const struct scic_sds_io_request_state_handler scic_sds_ssp_task_request_started_substate_handler_table[];
265 extern const struct sci_base_state scic_sds_smp_request_started_substate_table[];
266 extern const struct scic_sds_io_request_state_handler scic_sds_smp_request_started_substate_handler_table[];
271 * This macro returns the maximum number of SGL element paris that we will
272 * support in a single IO request.
274 #define SCU_MAX_SGL_ELEMENT_PAIRS ((SCU_IO_REQUEST_SGE_COUNT + 1) / 2)
277 * scic_sds_request_get_controller() -
279 * This macro will return the controller for this io request object
281 #define scic_sds_request_get_controller(this_request) \
282 ((this_request)->owning_controller)
285 * scic_sds_request_get_device() -
287 * This macro will return the device for this io request object
289 #define scic_sds_request_get_device(this_request) \
290 ((this_request)->target_device)
293 * scic_sds_request_get_port() -
295 * This macro will return the port for this io request object
297 #define scic_sds_request_get_port(this_request) \
298 scic_sds_remote_device_get_port(scic_sds_request_get_device(this_request))
301 * scic_sds_request_get_post_context() -
303 * This macro returns the constructed post context result for the io request.
305 #define scic_sds_request_get_post_context(this_request) \
306 ((this_request)->post_context)
309 * scic_sds_request_get_task_context() -
311 * This is a helper macro to return the os handle for this request object.
313 #define scic_sds_request_get_task_context(request) \
314 ((request)->task_context_buffer)
317 * scic_sds_request_set_status() -
319 * This macro will set the scu hardware status and sci request completion
320 * status for an io request.
322 #define scic_sds_request_set_status(request, scu_status_code, sci_status_code) \
324 (request)->scu_status = (scu_status_code); \
325 (request)->sci_status = (sci_status_code); \
328 #define scic_sds_request_complete(a_request) \
329 ((a_request)->state_handlers->parent.complete_handler(&(a_request)->parent))
335 * scic_sds_io_request_tc_completion() -
337 * This macro invokes the core state task completion handler for the
338 * SCIC_SDS_IO_REQUEST_T object.
340 #define scic_sds_io_request_tc_completion(this_request, completion_code) \
342 if (this_request->parent.state_machine.current_state_id \
343 == SCI_BASE_REQUEST_STATE_STARTED \
344 && this_request->has_started_substate_machine \
346 scic_sds_request_started_state_tc_completion_handler(this_request, completion_code); \
348 this_request->state_handlers->tc_completion_handler(this_request, completion_code); \
354 * This macro zeros the hardware SGL element data
356 #define SCU_SGL_ZERO(scu_sge) \
358 (scu_sge).length = 0; \
359 (scu_sge).address_lower = 0; \
360 (scu_sge).address_upper = 0; \
361 (scu_sge).address_modifier = 0; \
367 * This macro copys the SGL Element data from the host os to the hardware SGL
370 #define SCU_SGL_COPY(scu_sge, os_sge) \
372 (scu_sge).length = sg_dma_len(sg); \
373 (scu_sge).address_upper = \
374 upper_32_bits(sg_dma_address(sg)); \
375 (scu_sge).address_lower = \
376 lower_32_bits(sg_dma_address(sg)); \
377 (scu_sge).address_modifier = 0; \
381 * scic_sds_request_get_user_request() -
383 * This is a helper macro to return the os handle for this request object.
385 #define scic_sds_request_get_user_request(request) \
386 ((request)->user_request)
389 * *****************************************************************************
390 * * CORE REQUEST PROTOTYPES
391 * ***************************************************************************** */
393 void scic_sds_request_build_sgl(
394 struct scic_sds_request *this_request);
398 void scic_sds_stp_request_assign_buffers(
399 struct scic_sds_request *this_request);
401 void scic_sds_smp_request_assign_buffers(
402 struct scic_sds_request *this_request);
404 /* --------------------------------------------------------------------------- */
406 enum sci_status scic_sds_request_start(
407 struct scic_sds_request *this_request);
409 enum sci_status scic_sds_io_request_terminate(
410 struct scic_sds_request *this_request);
412 enum sci_status scic_sds_io_request_complete(
413 struct scic_sds_request *this_request);
415 void scic_sds_io_request_copy_response(
416 struct scic_sds_request *this_request);
418 enum sci_status scic_sds_io_request_event_handler(
419 struct scic_sds_request *this_request,
422 enum sci_status scic_sds_io_request_frame_handler(
423 struct scic_sds_request *this_request,
427 enum sci_status scic_sds_task_request_terminate(
428 struct scic_sds_request *this_request);
431 * *****************************************************************************
432 * * DEFAULT STATE HANDLERS
433 * ***************************************************************************** */
435 enum sci_status scic_sds_request_default_start_handler(
436 struct sci_base_request *this_request);
439 enum sci_status scic_sds_request_default_complete_handler(
440 struct sci_base_request *this_request);
442 enum sci_status scic_sds_request_default_destruct_handler(
443 struct sci_base_request *this_request);
445 enum sci_status scic_sds_request_default_tc_completion_handler(
446 struct scic_sds_request *this_request,
447 u32 completion_code);
449 enum sci_status scic_sds_request_default_event_handler(
450 struct scic_sds_request *this_request,
453 enum sci_status scic_sds_request_default_frame_handler(
454 struct scic_sds_request *this_request,
458 * *****************************************************************************
459 * * STARTED STATE HANDLERS
460 * ***************************************************************************** */
462 enum sci_status scic_sds_request_started_state_abort_handler(
463 struct sci_base_request *this_request);
465 enum sci_status scic_sds_request_started_state_tc_completion_handler(
466 struct scic_sds_request *this_request,
467 u32 completion_code);
469 #endif /* _SCIC_SDS_IO_REQUEST_H_ */