Commit b09ee1cd authored by Maximilian Luz's avatar Maximilian Luz Committed by Hans de Goede
Browse files

platform/surface: aggregator: Rename top-level request functions to avoid ambiguities 

We currently have a struct ssam_request_sync and a function
ssam_request_sync(). While this is valid C, there are some downsides to
it.

One of these is that current Sphinx versions (>= 3.0) cannot
disambiguate between the two (see disucssion and pull request linked
below). It instead emits a "WARNING: Duplicate C declaration" and links
for the struct and function in the resulting documentation link to the
same entry (i.e. both to either function or struct documentation)
instead of their respective own entries.

While we could just ignore that and wait for a fix, there's also a point
to be made that the current naming can be somewhat confusing when
searching (e.g. via grep) or trying to understand the levels of
abstraction at play:

We currently have struct ssam_request_sync and associated functions
ssam_request_sync_[alloc|free|init|wait|...]() operating on this struct.
However, function ssam_request_sync() is one abstraction level above
this. Similarly, ssam_request_sync_with_buffer() is not a function
operating on struct ssam_request_sync, but rather a sibling to
ssam_request_sync(), both using the struct under the hood.

Therefore, rename the top level request functions:

  ssam_request_sync() -> ssam_request_do_sync()
  ssam_request_sync_with_buffer() -> ssam_request_do_sync_with_buffer()
  ssam_request_sync_onstack() -> ssam_request_do_sync_onstack()

Link: https://lore.kernel.org/all/085e0ada65c11da9303d07e70c510dc45f21315b.1656756450.git.mchehab@kernel.org/
Link: https://github.com/sphinx-doc/sphinx/pull/8313


Signed-off-by: default avatarMaximilian Luz <luzmaximilian@gmail.com>
Link: https://lore.kernel.org/r/20221220175608.1436273-2-luzmaximilian@gmail.com


Reviewed-by: default avatarHans de Goede <hdegoede@redhat.com>
Signed-off-by: default avatarHans de Goede <hdegoede@redhat.com>
parent 13eca7d7

Documentation/driver-api/surface_aggregator/client.rst

+4 −4
Original line number Diff line number Diff line
@@ -19,7 +19,7 @@ 
.. |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>`
@@ -209,12 +209,12 @@ data received from it is converted from little-endian to host endianness. 
            * 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().
@@ -230,7 +230,7 @@ data received from it is converted from little-endian to host endianness. 
           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.

drivers/hid/surface-hid/surface_hid.c

+3 −3
Original line number Diff line number Diff line
@@ -80,7 +80,7 @@ static int ssam_hid_get_descriptor(struct surface_hid_device *shid, u8 entry, u8 


		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;
@@ -131,7 +131,7 @@ static int ssam_hid_set_raw_report(struct surface_hid_device *shid, u8 rprt_id, 


	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)
@@ -151,7 +151,7 @@ static int ssam_hid_get_raw_report(struct surface_hid_device *shid, u8 rprt_id, 
	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)

drivers/hid/surface-hid/surface_kbd.c

+3 −3
Original line number Diff line number Diff line
@@ -49,7 +49,7 @@ static int ssam_kbd_get_descriptor(struct surface_hid_device *shid, u8 entry, u8 
	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;
@@ -75,7 +75,7 @@ static int ssam_kbd_set_caps_led(struct surface_hid_device *shid, bool value) 
	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)
@@ -97,7 +97,7 @@ static int ssam_kbd_get_feature_report(struct surface_hid_device *shid, u8 *buf, 
	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;

drivers/platform/surface/aggregator/bus.c

+3 −3
Original line number Diff line number Diff line
@@ -136,9 +136,9 @@ int ssam_device_add(struct ssam_device *sdev) 
	 * 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

drivers/platform/surface/aggregator/controller.c

+16 −16
Original line number Diff line number Diff line
@@ -1674,7 +1674,7 @@ int ssam_request_sync_submit(struct ssam_controller *ctrl, 
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.
@@ -1686,7 +1686,7 @@ EXPORT_SYMBOL_GPL(ssam_request_sync_submit); 
 *

 * Return: Returns the status of the request or any failure during setup.

 */

int ssam_request_sync(struct ssam_controller *ctrl,

int ssam_request_do_sync(struct ssam_controller *ctrl,

			 const struct ssam_request *spec,

			 struct ssam_response *rsp)

{
@@ -1722,10 +1722,10 @@ int ssam_request_sync(struct ssam_controller *ctrl, 
	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.
@@ -1738,14 +1738,14 @@ EXPORT_SYMBOL_GPL(ssam_request_sync); 
 * 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,

int ssam_request_do_sync_with_buffer(struct ssam_controller *ctrl,

				     const struct ssam_request *spec,

				     struct ssam_response *rsp,

				     struct ssam_span *buf)
@@ -1772,7 +1772,7 @@ int ssam_request_sync_with_buffer(struct ssam_controller *ctrl, 


	return status;

}

EXPORT_SYMBOL_GPL(ssam_request_sync_with_buffer);

EXPORT_SYMBOL_GPL(ssam_request_do_sync_with_buffer);





/* -- Internal SAM requests. ------------------------------------------------ */
@@ -1864,7 +1864,7 @@ static int __ssam_ssh_event_request(struct ssam_controller *ctrl, 
	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;