.. |ssam_notifier_unregister| replace:: :c:func:`ssam_notifier_unregister`
.. |ssam_device_notifier_register| replace:: :c:func:`ssam_device_notifier_register`
.. |ssam_device_notifier_unregister| replace:: :c:func:`ssam_device_notifier_unregister`
-.. |ssam_request_sync| replace:: :c:func:`ssam_request_sync`
+.. |ssam_request_do_sync| replace:: :c:func:`ssam_request_do_sync`
.. |ssam_event_mask| replace:: :c:type:`enum ssam_event_mask <ssam_event_mask>`
* with the SSAM_REQUEST_HAS_RESPONSE flag set in the specification
* above.
*/
- status = ssam_request_sync(ctrl, &rqst, &resp);
+ status = ssam_request_do_sync(ctrl, &rqst, &resp);
/*
* Alternatively use
*
- * ssam_request_sync_onstack(ctrl, &rqst, &resp, sizeof(arg_le));
+ * ssam_request_do_sync_onstack(ctrl, &rqst, &resp, sizeof(arg_le));
*
* to perform the request, allocating the message buffer directly
* on the stack as opposed to allocation via kzalloc().
return status;
}
-Note that |ssam_request_sync| in its essence is a wrapper over lower-level
+Note that |ssam_request_do_sync| in its essence is a wrapper over lower-level
request primitives, which may also be used to perform requests. Refer to its
implementation and documentation for more details.
rsp.length = 0;
- status = ssam_retry(ssam_request_sync_onstack, shid->ctrl, &rqst, &rsp,
+ status = ssam_retry(ssam_request_do_sync_onstack, shid->ctrl, &rqst, &rsp,
sizeof(*slice));
if (status)
return status;
buf[0] = rprt_id;
- return ssam_retry(ssam_request_sync, shid->ctrl, &rqst, NULL);
+ return ssam_retry(ssam_request_do_sync, shid->ctrl, &rqst, NULL);
}
static int ssam_hid_get_raw_report(struct surface_hid_device *shid, u8 rprt_id, u8 *buf, size_t len)
rsp.length = 0;
rsp.pointer = buf;
- return ssam_retry(ssam_request_sync_onstack, shid->ctrl, &rqst, &rsp, sizeof(rprt_id));
+ return ssam_retry(ssam_request_do_sync_onstack, shid->ctrl, &rqst, &rsp, sizeof(rprt_id));
}
static u32 ssam_hid_event_fn(struct ssam_event_notifier *nf, const struct ssam_event *event)
rsp.length = 0;
rsp.pointer = buf;
- status = ssam_retry(ssam_request_sync_onstack, shid->ctrl, &rqst, &rsp, sizeof(entry));
+ status = ssam_retry(ssam_request_do_sync_onstack, shid->ctrl, &rqst, &rsp, sizeof(entry));
if (status)
return status;
rqst.length = sizeof(value_u8);
rqst.payload = &value_u8;
- return ssam_retry(ssam_request_sync_onstack, shid->ctrl, &rqst, NULL, sizeof(value_u8));
+ return ssam_retry(ssam_request_do_sync_onstack, shid->ctrl, &rqst, NULL, sizeof(value_u8));
}
static int ssam_kbd_get_feature_report(struct surface_hid_device *shid, u8 *buf, size_t len)
rsp.length = 0;
rsp.pointer = buf;
- status = ssam_retry(ssam_request_sync_onstack, shid->ctrl, &rqst, &rsp, sizeof(payload));
+ status = ssam_retry(ssam_request_do_sync_onstack, shid->ctrl, &rqst, &rsp, sizeof(payload));
if (status)
return status;
* is always valid and can be used for requests as long as the client
* device we add here is registered as child under it. This essentially
* guarantees that the client driver can always expect the preconditions
- * for functions like ssam_request_sync (controller has to be started
- * and is not suspended) to hold and thus does not have to check for
- * them.
+ * for functions like ssam_request_do_sync() (controller has to be
+ * started and is not suspended) to hold and thus does not have to check
+ * for them.
*
* Note that for this to work, the controller has to be a parent device.
* If it is not a direct parent, care has to be taken that the device is
EXPORT_SYMBOL_GPL(ssam_request_sync_submit);
/**
- * ssam_request_sync() - Execute a synchronous request.
+ * ssam_request_do_sync() - Execute a synchronous request.
* @ctrl: The controller via which the request will be submitted.
* @spec: The request specification and payload.
* @rsp: The response buffer.
*
* Return: Returns the status of the request or any failure during setup.
*/
-int ssam_request_sync(struct ssam_controller *ctrl,
- const struct ssam_request *spec,
- struct ssam_response *rsp)
+int ssam_request_do_sync(struct ssam_controller *ctrl,
+ const struct ssam_request *spec,
+ struct ssam_response *rsp)
{
struct ssam_request_sync *rqst;
struct ssam_span buf;
ssam_request_sync_free(rqst);
return status;
}
-EXPORT_SYMBOL_GPL(ssam_request_sync);
+EXPORT_SYMBOL_GPL(ssam_request_do_sync);
/**
- * ssam_request_sync_with_buffer() - Execute a synchronous request with the
+ * ssam_request_do_sync_with_buffer() - Execute a synchronous request with the
* provided buffer as back-end for the message buffer.
* @ctrl: The controller via which the request will be submitted.
* @spec: The request specification and payload.
* SSH_COMMAND_MESSAGE_LENGTH() macro can be used to compute the required
* message buffer size.
*
- * This function does essentially the same as ssam_request_sync(), but instead
- * of dynamically allocating the request and message data buffer, it uses the
- * provided message data buffer and stores the (small) request struct on the
- * heap.
+ * This function does essentially the same as ssam_request_do_sync(), but
+ * instead of dynamically allocating the request and message data buffer, it
+ * uses the provided message data buffer and stores the (small) request struct
+ * on the heap.
*
* Return: Returns the status of the request or any failure during setup.
*/
-int ssam_request_sync_with_buffer(struct ssam_controller *ctrl,
- const struct ssam_request *spec,
- struct ssam_response *rsp,
- struct ssam_span *buf)
+int ssam_request_do_sync_with_buffer(struct ssam_controller *ctrl,
+ const struct ssam_request *spec,
+ struct ssam_response *rsp,
+ struct ssam_span *buf)
{
struct ssam_request_sync rqst;
ssize_t len;
return status;
}
-EXPORT_SYMBOL_GPL(ssam_request_sync_with_buffer);
+EXPORT_SYMBOL_GPL(ssam_request_do_sync_with_buffer);
/* -- Internal SAM requests. ------------------------------------------------ */
result.length = 0;
result.pointer = &buf;
- status = ssam_retry(ssam_request_sync_onstack, ctrl, &rqst, &result,
+ status = ssam_retry(ssam_request_do_sync_onstack, ctrl, &rqst, &result,
sizeof(params));
return status < 0 ? status : buf;
return san_rqst_fixup_suspended(d, &rqst, buffer);
}
- status = __ssam_retry(ssam_request_sync_onstack, SAN_REQUEST_NUM_TRIES,
+ status = __ssam_retry(ssam_request_do_sync_onstack, SAN_REQUEST_NUM_TRIES,
d->ctrl, &rqst, &rsp, SAN_GSB_MAX_RQSX_PAYLOAD);
if (!status) {
* theoretical maximum (SSH_COMMAND_MAX_PAYLOAD_SIZE) of the
* underlying protocol (note that nothing remotely this size
* should ever be allocated in any normal case). This size is
- * validated later in ssam_request_sync(), for allocation the
- * bound imposed by u16 should be enough.
+ * validated later in ssam_request_do_sync(), for allocation
+ * the bound imposed by u16 should be enough.
*/
spec.payload = kzalloc(spec.length, GFP_KERNEL);
if (!spec.payload) {
}
/* Perform request. */
- status = ssam_request_sync(client->cdev->ctrl, &spec, &rsp);
+ status = ssam_request_do_sync(client->cdev->ctrl, &spec, &rsp);
if (status)
goto out;
rsp.length = 0;
rsp.pointer = (u8 *)sources;
- status = ssam_retry(ssam_request_sync_onstack, sw->sdev->ctrl, &rqst, &rsp, 0);
+ status = ssam_retry(ssam_request_do_sync_onstack, sw->sdev->ctrl, &rqst, &rsp, 0);
if (status)
return status;
return rqst->status;
}
-int ssam_request_sync(struct ssam_controller *ctrl,
- const struct ssam_request *spec,
- struct ssam_response *rsp);
+int ssam_request_do_sync(struct ssam_controller *ctrl,
+ const struct ssam_request *spec,
+ struct ssam_response *rsp);
-int ssam_request_sync_with_buffer(struct ssam_controller *ctrl,
- const struct ssam_request *spec,
- struct ssam_response *rsp,
- struct ssam_span *buf);
+int ssam_request_do_sync_with_buffer(struct ssam_controller *ctrl,
+ const struct ssam_request *spec,
+ struct ssam_response *rsp,
+ struct ssam_span *buf);
/**
- * ssam_request_sync_onstack - Execute a synchronous request on the stack.
+ * ssam_request_do_sync_onstack - Execute a synchronous request on the stack.
* @ctrl: The controller via which the request is submitted.
* @rqst: The request specification.
* @rsp: The response buffer.
* fully initializes it via the provided request specification, submits it,
* and finally waits for its completion before returning its status. This
* helper macro essentially allocates the request message buffer on the stack
- * and then calls ssam_request_sync_with_buffer().
+ * and then calls ssam_request_do_sync_with_buffer().
*
* Note: The @payload_len parameter specifies the maximum payload length, used
* for buffer allocation. The actual payload length may be smaller.
* Return: Returns the status of the request or any failure during setup, i.e.
* zero on success and a negative value on failure.
*/
-#define ssam_request_sync_onstack(ctrl, rqst, rsp, payload_len) \
+#define ssam_request_do_sync_onstack(ctrl, rqst, rsp, payload_len) \
({ \
u8 __data[SSH_COMMAND_MESSAGE_LENGTH(payload_len)]; \
struct ssam_span __buf = { &__data[0], ARRAY_SIZE(__data) }; \
\
- ssam_request_sync_with_buffer(ctrl, rqst, rsp, &__buf); \
+ ssam_request_do_sync_with_buffer(ctrl, rqst, rsp, &__buf); \
})
/**
* zero on success and negative on failure. The ``ctrl`` parameter is the
* controller via which the request is being sent.
*
- * Refer to ssam_request_sync_onstack() for more details on the behavior of
+ * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
* the generated function.
*/
#define SSAM_DEFINE_SYNC_REQUEST_N(name, spec...) \
rqst.length = 0; \
rqst.payload = NULL; \
\
- return ssam_request_sync_onstack(ctrl, &rqst, NULL, 0); \
+ return ssam_request_do_sync_onstack(ctrl, &rqst, NULL, 0); \
}
/**
* parameter is the controller via which the request is sent. The request
* argument is specified via the ``arg`` pointer.
*
- * Refer to ssam_request_sync_onstack() for more details on the behavior of
+ * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
* the generated function.
*/
#define SSAM_DEFINE_SYNC_REQUEST_W(name, atype, spec...) \
rqst.length = sizeof(atype); \
rqst.payload = (u8 *)arg; \
\
- return ssam_request_sync_onstack(ctrl, &rqst, NULL, \
- sizeof(atype)); \
+ return ssam_request_do_sync_onstack(ctrl, &rqst, NULL, \
+ sizeof(atype)); \
}
/**
* the controller via which the request is sent. The request's return value is
* written to the memory pointed to by the ``ret`` parameter.
*
- * Refer to ssam_request_sync_onstack() for more details on the behavior of
+ * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
* the generated function.
*/
#define SSAM_DEFINE_SYNC_REQUEST_R(name, rtype, spec...) \
rsp.length = 0; \
rsp.pointer = (u8 *)ret; \
\
- status = ssam_request_sync_onstack(ctrl, &rqst, &rsp, 0); \
+ status = ssam_request_do_sync_onstack(ctrl, &rqst, &rsp, 0); \
if (status) \
return status; \
\
* request argument is specified via the ``arg`` pointer. The request's return
* value is written to the memory pointed to by the ``ret`` parameter.
*
- * Refer to ssam_request_sync_onstack() for more details on the behavior of
+ * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
* the generated function.
*/
#define SSAM_DEFINE_SYNC_REQUEST_WR(name, atype, rtype, spec...) \
rsp.length = 0; \
rsp.pointer = (u8 *)ret; \
\
- status = ssam_request_sync_onstack(ctrl, &rqst, &rsp, sizeof(atype)); \
+ status = ssam_request_do_sync_onstack(ctrl, &rqst, &rsp, sizeof(atype)); \
if (status) \
return status; \
\
* parameter is the controller via which the request is sent, ``tid`` the
* target ID for the request, and ``iid`` the instance ID.
*
- * Refer to ssam_request_sync_onstack() for more details on the behavior of
+ * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
* the generated function.
*/
#define SSAM_DEFINE_SYNC_REQUEST_MD_N(name, spec...) \
rqst.length = 0; \
rqst.payload = NULL; \
\
- return ssam_request_sync_onstack(ctrl, &rqst, NULL, 0); \
+ return ssam_request_do_sync_onstack(ctrl, &rqst, NULL, 0); \
}
/**
* ``tid`` the target ID for the request, and ``iid`` the instance ID. The
* request argument is specified via the ``arg`` pointer.
*
- * Refer to ssam_request_sync_onstack() for more details on the behavior of
+ * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
* the generated function.
*/
#define SSAM_DEFINE_SYNC_REQUEST_MD_W(name, atype, spec...) \
rqst.length = sizeof(atype); \
rqst.payload = (u8 *)arg; \
\
- return ssam_request_sync_onstack(ctrl, &rqst, NULL, \
+ return ssam_request_do_sync_onstack(ctrl, &rqst, NULL, \
sizeof(atype)); \
}
* the target ID for the request, and ``iid`` the instance ID. The request's
* return value is written to the memory pointed to by the ``ret`` parameter.
*
- * Refer to ssam_request_sync_onstack() for more details on the behavior of
+ * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
* the generated function.
*/
#define SSAM_DEFINE_SYNC_REQUEST_MD_R(name, rtype, spec...) \
rsp.length = 0; \
rsp.pointer = (u8 *)ret; \
\
- status = ssam_request_sync_onstack(ctrl, &rqst, &rsp, 0); \
+ status = ssam_request_do_sync_onstack(ctrl, &rqst, &rsp, 0); \
if (status) \
return status; \
\
* The request argument is specified via the ``arg`` pointer. The request's
* return value is written to the memory pointed to by the ``ret`` parameter.
*
- * Refer to ssam_request_sync_onstack() for more details on the behavior of
+ * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
* the generated function.
*/
#define SSAM_DEFINE_SYNC_REQUEST_MD_WR(name, atype, rtype, spec...) \
rsp.length = 0; \
rsp.pointer = (u8 *)ret; \
\
- status = ssam_request_sync_onstack(ctrl, &rqst, &rsp, sizeof(atype)); \
+ status = ssam_request_do_sync_onstack(ctrl, &rqst, &rsp, sizeof(atype)); \
if (status) \
return status; \
\
* device of the request and by association the controller via which the
* request is sent.
*
- * Refer to ssam_request_sync_onstack() for more details on the behavior of
+ * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
* the generated function.
*/
#define SSAM_DEFINE_SYNC_REQUEST_CL_N(name, spec...) \
* which the request is sent. The request's argument is specified via the
* ``arg`` pointer.
*
- * Refer to ssam_request_sync_onstack() for more details on the behavior of
+ * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
* the generated function.
*/
#define SSAM_DEFINE_SYNC_REQUEST_CL_W(name, atype, spec...) \
* the request is sent. The request's return value is written to the memory
* pointed to by the ``ret`` parameter.
*
- * Refer to ssam_request_sync_onstack() for more details on the behavior of
+ * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
* the generated function.
*/
#define SSAM_DEFINE_SYNC_REQUEST_CL_R(name, rtype, spec...) \
* specified via the ``arg`` pointer. The request's return value is written to
* the memory pointed to by the ``ret`` parameter.
*
- * Refer to ssam_request_sync_onstack() for more details on the behavior of
+ * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
* the generated function.
*/
#define SSAM_DEFINE_SYNC_REQUEST_CL_WR(name, atype, rtype, spec...) \