diff options
Diffstat (limited to 'Documentation/driver-api/surface_aggregator')
| -rw-r--r-- | Documentation/driver-api/surface_aggregator/client.rst | 12 | ||||
| -rw-r--r-- | Documentation/driver-api/surface_aggregator/ssh.rst | 36 |
2 files changed, 25 insertions, 23 deletions
diff --git a/Documentation/driver-api/surface_aggregator/client.rst b/Documentation/driver-api/surface_aggregator/client.rst index 27f95abdbe99..e100ab0a24cc 100644 --- a/Documentation/driver-api/surface_aggregator/client.rst +++ b/Documentation/driver-api/surface_aggregator/client.rst @@ -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>` @@ -191,7 +191,7 @@ data received from it is converted from little-endian to host endianness. * they do not correspond to an actual SAM/EC request. */ rqst.target_category = SSAM_SSH_TC_SAM; - rqst.target_id = 0x01; + rqst.target_id = SSAM_SSH_TID_SAM; rqst.command_id = 0x02; rqst.instance_id = 0x03; rqst.flags = SSAM_REQUEST_HAS_RESPONSE; @@ -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. @@ -241,7 +241,7 @@ one of the generator macros, for example via: SSAM_DEFINE_SYNC_REQUEST_W(__ssam_tmp_perf_mode_set, __le32, { .target_category = SSAM_SSH_TC_TMP, - .target_id = 0x01, + .target_id = SSAM_SSH_TID_SAM, .command_id = 0x03, .instance_id = 0x00, }); diff --git a/Documentation/driver-api/surface_aggregator/ssh.rst b/Documentation/driver-api/surface_aggregator/ssh.rst index bf007d6c9873..18fd0f0aee84 100644 --- a/Documentation/driver-api/surface_aggregator/ssh.rst +++ b/Documentation/driver-api/surface_aggregator/ssh.rst @@ -13,6 +13,7 @@ .. |DATA_NSQ| replace:: ``DATA_NSQ`` .. |TC| replace:: ``TC`` .. |TID| replace:: ``TID`` +.. |SID| replace:: ``SID`` .. |IID| replace:: ``IID`` .. |RQID| replace:: ``RQID`` .. |CID| replace:: ``CID`` @@ -219,13 +220,13 @@ following fields, packed together and in order: - |u8| - Target category. - * - |TID| (out) + * - |TID| - |u8| - - Target ID for outgoing (host to EC) commands. + - Target ID for commands/messages. - * - |TID| (in) + * - |SID| - |u8| - - Target ID for incoming (EC to host) commands. + - Source ID for commands/messages. * - |IID| - |u8| @@ -286,19 +287,20 @@ general, however, a single target category should map to a single reserved event request ID. Furthermore, requests, responses, and events have an associated target ID -(``TID``). This target ID is split into output (host to EC) and input (EC to -host) fields, with the respecting other field (e.g. output field on incoming -messages) set to zero. Two ``TID`` values are known: Primary (``0x01``) and -secondary (``0x02``). In general, the response to a request should have the -same ``TID`` value, however, the field (output vs. input) should be used in -accordance to the direction in which the response is sent (i.e. on the input -field, as responses are generally sent from the EC to the host). - -Note that, even though requests and events should be uniquely identifiable -by target category and command ID alone, the EC may require specific -target ID and instance ID values to accept a command. A command that is -accepted for ``TID=1``, for example, may not be accepted for ``TID=2`` -and vice versa. +(``TID``) and source ID (``SID``). These two fields indicate where a message +originates from (``SID``) and what the intended target of the message is +(``TID``). Note that a response to a specific request therefore has the source +and target IDs swapped when compared to the original request (i.e. the request +target is the response source and the request source is the response target). +See (:c:type:`enum ssh_request_id <ssh_request_id>`) for possible values of +both. + +Note that, even though requests and events should be uniquely identifiable by +target category and command ID alone, the EC may require specific target ID and +instance ID values to accept a command. A command that is accepted for +``TID=1``, for example, may not be accepted for ``TID=2`` and vice versa. While +this may not always hold in reality, you can think of different target/source +IDs indicating different physical ECs with potentially different feature sets. Limitations and Observations |