Something went wrong. Try again.
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Something went wrong. Try again.
38 kB · 994 lines
C
at master
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995/* SPDX-License-Identifier: GPL-2.0+ *//* * Surface System Aggregator Module (SSAM) controller interface. * * Main communication interface for the SSAM EC. Provides a controller * managing access and communication to and from the SSAM EC, as well as main * communication structures and definitions. * * Copyright (C) 2019-2021 Maximilian Luz <luzmaximilian@gmail.com> */
#ifndef _LINUX_SURFACE_AGGREGATOR_CONTROLLER_H#define _LINUX_SURFACE_AGGREGATOR_CONTROLLER_H
#include <linux/completion.h>#include <linux/device.h>#include <linux/types.h>
#include <linux/surface_aggregator/serial_hub.h>
/* -- Main data types and definitions --------------------------------------- */
/** * enum ssam_event_flags - Flags for enabling/disabling SAM events * @SSAM_EVENT_SEQUENCED: The event will be sent via a sequenced data frame. */enum ssam_event_flags { SSAM_EVENT_SEQUENCED = BIT(0),};
/** * struct ssam_event - SAM event sent from the EC to the host. * @target_category: Target category of the event source. See &enum ssam_ssh_tc. * @target_id: Target ID of the event source. * @command_id: Command ID of the event. * @instance_id: Instance ID of the event source. * @length: Length of the event payload in bytes. * @data: Event payload data. */struct ssam_event { u8 target_category; u8 target_id; u8 command_id; u8 instance_id; u16 length; u8 data[] __counted_by(length);};
/** * enum ssam_request_flags - Flags for SAM requests. * * @SSAM_REQUEST_HAS_RESPONSE: * Specifies that the request expects a response. If not set, the request * will be directly completed after its underlying packet has been * transmitted. If set, the request transport system waits for a response * of the request. * * @SSAM_REQUEST_UNSEQUENCED: * Specifies that the request should be transmitted via an unsequenced * packet. If set, the request must not have a response, meaning that this * flag and the %SSAM_REQUEST_HAS_RESPONSE flag are mutually exclusive. */enum ssam_request_flags { SSAM_REQUEST_HAS_RESPONSE = BIT(0), SSAM_REQUEST_UNSEQUENCED = BIT(1),};
/** * struct ssam_request - SAM request description. * @target_category: Category of the request's target. See &enum ssam_ssh_tc. * @target_id: ID of the request's target. * @command_id: Command ID of the request. * @instance_id: Instance ID of the request's target. * @flags: Flags for the request. See &enum ssam_request_flags. * @length: Length of the request payload in bytes. * @payload: Request payload data. * * This struct fully describes a SAM request with payload. It is intended to * help set up the actual transport struct, e.g. &struct ssam_request_sync, * and specifically its raw message data via ssam_request_write_data(). */struct ssam_request { u8 target_category; u8 target_id; u8 command_id; u8 instance_id; u16 flags; u16 length; const u8 *payload;};
/** * struct ssam_response - Response buffer for SAM request. * @capacity: Capacity of the buffer, in bytes. * @length: Length of the actual data stored in the memory pointed to by * @pointer, in bytes. Set by the transport system. * @pointer: Pointer to the buffer's memory, storing the response payload data. */struct ssam_response { size_t capacity; size_t length; u8 *pointer;};
struct ssam_controller;
struct ssam_controller *ssam_get_controller(void);struct ssam_controller *ssam_client_bind(struct device *client);int ssam_client_link(struct ssam_controller *ctrl, struct device *client);
struct device *ssam_controller_device(struct ssam_controller *c);
struct ssam_controller *ssam_controller_get(struct ssam_controller *c);void ssam_controller_put(struct ssam_controller *c);
void ssam_controller_statelock(struct ssam_controller *c);void ssam_controller_stateunlock(struct ssam_controller *c);
ssize_t ssam_request_write_data(struct ssam_span *buf, struct ssam_controller *ctrl, const struct ssam_request *spec);
/* -- Synchronous request interface. ---------------------------------------- */
/** * struct ssam_request_sync - Synchronous SAM request struct. * @base: Underlying SSH request. * @comp: Completion used to signal full completion of the request. After the * request has been submitted, this struct may only be modified or * deallocated after the completion has been signaled. * request has been submitted, * @resp: Buffer to store the response. * @status: Status of the request, set after the base request has been * completed or has failed. */struct ssam_request_sync { struct ssh_request base; struct completion comp; struct ssam_response *resp; int status;};
int ssam_request_sync_alloc(size_t payload_len, gfp_t flags, struct ssam_request_sync **rqst, struct ssam_span *buffer);
void ssam_request_sync_free(struct ssam_request_sync *rqst);
int ssam_request_sync_init(struct ssam_request_sync *rqst, enum ssam_request_flags flags);
/** * ssam_request_sync_set_data - Set message data of a synchronous request. * @rqst: The request. * @ptr: Pointer to the request message data. * @len: Length of the request message data. * * Set the request message data of a synchronous request. The provided buffer * needs to live until the request has been completed. */static inline void ssam_request_sync_set_data(struct ssam_request_sync *rqst, u8 *ptr, size_t len){ ssh_request_set_data(&rqst->base, ptr, len);}
/** * ssam_request_sync_set_resp - Set response buffer of a synchronous request. * @rqst: The request. * @resp: The response buffer. * * Sets the response buffer of a synchronous request. This buffer will store * the response of the request after it has been completed. May be %NULL if no * response is expected. */static inline void ssam_request_sync_set_resp(struct ssam_request_sync *rqst, struct ssam_response *resp){ rqst->resp = resp;}
int ssam_request_sync_submit(struct ssam_controller *ctrl, struct ssam_request_sync *rqst);
/** * ssam_request_sync_wait - Wait for completion of a synchronous request. * @rqst: The request to wait for. * * Wait for completion and release of a synchronous request. After this * function terminates, the request is guaranteed to have left the transport * system. After successful submission of a request, this function must be * called before accessing the response of the request, freeing the request, * or freeing any of the buffers associated with the request. * * This function must not be called if the request has not been submitted yet * and may lead to a deadlock/infinite wait if a subsequent request submission * fails in that case, due to the completion never triggering. * * Return: Returns the status of the given request, which is set on completion * of the packet. This value is zero on success and negative on failure. */static inline int ssam_request_sync_wait(struct ssam_request_sync *rqst){ wait_for_completion(&rqst->comp); return rqst->status;}
int ssam_request_do_sync(struct ssam_controller *ctrl, const struct ssam_request *spec, struct ssam_response *rsp);
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_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. * @payload_len: The (maximum) request payload length. * * Allocates a synchronous request with specified payload length on the stack, * 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_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_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_do_sync_with_buffer(ctrl, rqst, rsp, &__buf); \ })
/** * __ssam_retry - Retry request in case of I/O errors or timeouts. * @request: The request function to execute. Must return an integer. * @n: Number of tries. * @args: Arguments for the request function. * * Executes the given request function, i.e. calls @request. In case the * request returns %-EREMOTEIO (indicates I/O error) or %-ETIMEDOUT (request * or underlying packet timed out), @request will be re-executed again, up to * @n times in total. * * Return: Returns the return value of the last execution of @request. */#define __ssam_retry(request, n, args...) \ ({ \ int __i, __s = 0; \ \ for (__i = (n); __i > 0; __i--) { \ __s = request(args); \ if (__s != -ETIMEDOUT && __s != -EREMOTEIO) \ break; \ } \ __s; \ })
/** * ssam_retry - Retry request in case of I/O errors or timeouts up to three * times in total. * @request: The request function to execute. Must return an integer. * @args: Arguments for the request function. * * Executes the given request function, i.e. calls @request. In case the * request returns %-EREMOTEIO (indicates I/O error) or -%ETIMEDOUT (request * or underlying packet timed out), @request will be re-executed again, up to * three times in total. * * See __ssam_retry() for a more generic macro for this purpose. * * Return: Returns the return value of the last execution of @request. */#define ssam_retry(request, args...) \ __ssam_retry(request, 3, args)
/** * struct ssam_request_spec - Blue-print specification of SAM request. * @target_category: Category of the request's target. See &enum ssam_ssh_tc. * @target_id: ID of the request's target. * @command_id: Command ID of the request. * @instance_id: Instance ID of the request's target. * @flags: Flags for the request. See &enum ssam_request_flags. * * Blue-print specification for a SAM request. This struct describes the * unique static parameters of a request (i.e. type) without specifying any of * its instance-specific data (e.g. payload). It is intended to be used as base * for defining simple request functions via the * ``SSAM_DEFINE_SYNC_REQUEST_x()`` family of macros. */struct ssam_request_spec { u8 target_category; u8 target_id; u8 command_id; u8 instance_id; u8 flags;};
/** * struct ssam_request_spec_md - Blue-print specification for multi-device SAM * request. * @target_category: Category of the request's target. See &enum ssam_ssh_tc. * @command_id: Command ID of the request. * @flags: Flags for the request. See &enum ssam_request_flags. * * Blue-print specification for a multi-device SAM request, i.e. a request * that is applicable to multiple device instances, described by their * individual target and instance IDs. This struct describes the unique static * parameters of a request (i.e. type) without specifying any of its * instance-specific data (e.g. payload) and without specifying any of its * device specific IDs (i.e. target and instance ID). It is intended to be * used as base for defining simple multi-device request functions via the * ``SSAM_DEFINE_SYNC_REQUEST_MD_x()`` and ``SSAM_DEFINE_SYNC_REQUEST_CL_x()`` * families of macros. */struct ssam_request_spec_md { u8 target_category; u8 command_id; u8 flags;};
/** * SSAM_DEFINE_SYNC_REQUEST_N() - Define synchronous SAM request function * with neither argument nor return value. * @name: Name of the generated function. * @spec: Specification (&struct ssam_request_spec) defining the request. * * Defines a function executing the synchronous SAM request specified by * @spec, with the request having neither argument nor return value. The * generated function takes care of setting up the request struct and buffer * allocation, as well as execution of the request itself, returning once the * request has been fully completed. The required transport buffer will be * allocated on the stack. * * The generated function is defined as ``static int name(struct * ssam_controller *ctrl)``, returning the status of the request, which is * zero on success and negative on failure. The ``ctrl`` parameter is the * controller via which the request is being sent. * * 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...) \ static int name(struct ssam_controller *ctrl) \ { \ struct ssam_request_spec s = (struct ssam_request_spec)spec; \ struct ssam_request rqst; \ \ rqst.target_category = s.target_category; \ rqst.target_id = s.target_id; \ rqst.command_id = s.command_id; \ rqst.instance_id = s.instance_id; \ rqst.flags = s.flags; \ rqst.length = 0; \ rqst.payload = NULL; \ \ return ssam_request_do_sync_onstack(ctrl, &rqst, NULL, 0); \ }
/** * SSAM_DEFINE_SYNC_REQUEST_W() - Define synchronous SAM request function with * argument. * @name: Name of the generated function. * @atype: Type of the request's argument. * @spec: Specification (&struct ssam_request_spec) defining the request. * * Defines a function executing the synchronous SAM request specified by * @spec, with the request taking an argument of type @atype and having no * return value. The generated function takes care of setting up the request * struct, buffer allocation, as well as execution of the request itself, * returning once the request has been fully completed. The required transport * buffer will be allocated on the stack. * * The generated function is defined as ``static int name(struct * ssam_controller *ctrl, const atype *arg)``, returning the status of the * request, which is zero on success and negative on failure. The ``ctrl`` * parameter is the controller via which the request is sent. The request * argument is specified via the ``arg`` pointer. * * 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...) \ static int name(struct ssam_controller *ctrl, const atype *arg) \ { \ struct ssam_request_spec s = (struct ssam_request_spec)spec; \ struct ssam_request rqst; \ \ rqst.target_category = s.target_category; \ rqst.target_id = s.target_id; \ rqst.command_id = s.command_id; \ rqst.instance_id = s.instance_id; \ rqst.flags = s.flags; \ rqst.length = sizeof(atype); \ rqst.payload = (u8 *)arg; \ \ return ssam_request_do_sync_onstack(ctrl, &rqst, NULL, \ sizeof(atype)); \ }
/** * SSAM_DEFINE_SYNC_REQUEST_R() - Define synchronous SAM request function with * return value. * @name: Name of the generated function. * @rtype: Type of the request's return value. * @spec: Specification (&struct ssam_request_spec) defining the request. * * Defines a function executing the synchronous SAM request specified by * @spec, with the request taking no argument but having a return value of * type @rtype. The generated function takes care of setting up the request * and response structs, buffer allocation, as well as execution of the * request itself, returning once the request has been fully completed. The * required transport buffer will be allocated on the stack. * * The generated function is defined as ``static int name(struct * ssam_controller *ctrl, rtype *ret)``, returning the status of the request, * which is zero on success and negative on failure. The ``ctrl`` parameter is * 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_do_sync_onstack() for more details on the behavior of * the generated function. */#define SSAM_DEFINE_SYNC_REQUEST_R(name, rtype, spec...) \ static int name(struct ssam_controller *ctrl, rtype *ret) \ { \ struct ssam_request_spec s = (struct ssam_request_spec)spec; \ struct ssam_request rqst; \ struct ssam_response rsp; \ int status; \ \ rqst.target_category = s.target_category; \ rqst.target_id = s.target_id; \ rqst.command_id = s.command_id; \ rqst.instance_id = s.instance_id; \ rqst.flags = s.flags | SSAM_REQUEST_HAS_RESPONSE; \ rqst.length = 0; \ rqst.payload = NULL; \ \ rsp.capacity = sizeof(rtype); \ rsp.length = 0; \ rsp.pointer = (u8 *)ret; \ \ status = ssam_request_do_sync_onstack(ctrl, &rqst, &rsp, 0); \ if (status) \ return status; \ \ if (rsp.length != sizeof(rtype)) { \ struct device *dev = ssam_controller_device(ctrl); \ dev_err(dev, \ "rqst: invalid response length, expected %zu, got %zu (tc: %#04x, cid: %#04x)", \ sizeof(rtype), rsp.length, rqst.target_category,\ rqst.command_id); \ return -EIO; \ } \ \ return 0; \ }
/** * SSAM_DEFINE_SYNC_REQUEST_WR() - Define synchronous SAM request function with * both argument and return value. * @name: Name of the generated function. * @atype: Type of the request's argument. * @rtype: Type of the request's return value. * @spec: Specification (&struct ssam_request_spec) defining the request. * * Defines a function executing the synchronous SAM request specified by @spec, * with the request taking an argument of type @atype and having a return value * of type @rtype. The generated function takes care of setting up the request * and response structs, buffer allocation, as well as execution of the request * itself, returning once the request has been fully completed. The required * transport buffer will be allocated on the stack. * * The generated function is defined as ``static int name(struct * ssam_controller *ctrl, const atype *arg, rtype *ret)``, returning the status * of the request, which is zero on success and negative on failure. The * ``ctrl`` parameter is the controller via which the request is sent. 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_do_sync_onstack() for more details on the behavior of * the generated function. */#define SSAM_DEFINE_SYNC_REQUEST_WR(name, atype, rtype, spec...) \ static int name(struct ssam_controller *ctrl, const atype *arg, rtype *ret) \ { \ struct ssam_request_spec s = (struct ssam_request_spec)spec; \ struct ssam_request rqst; \ struct ssam_response rsp; \ int status; \ \ rqst.target_category = s.target_category; \ rqst.target_id = s.target_id; \ rqst.command_id = s.command_id; \ rqst.instance_id = s.instance_id; \ rqst.flags = s.flags | SSAM_REQUEST_HAS_RESPONSE; \ rqst.length = sizeof(atype); \ rqst.payload = (u8 *)arg; \ \ rsp.capacity = sizeof(rtype); \ rsp.length = 0; \ rsp.pointer = (u8 *)ret; \ \ status = ssam_request_do_sync_onstack(ctrl, &rqst, &rsp, sizeof(atype)); \ if (status) \ return status; \ \ if (rsp.length != sizeof(rtype)) { \ struct device *dev = ssam_controller_device(ctrl); \ dev_err(dev, \ "rqst: invalid response length, expected %zu, got %zu (tc: %#04x, cid: %#04x)", \ sizeof(rtype), rsp.length, rqst.target_category,\ rqst.command_id); \ return -EIO; \ } \ \ return 0; \ }
/** * SSAM_DEFINE_SYNC_REQUEST_MD_N() - Define synchronous multi-device SAM * request function with neither argument nor return value. * @name: Name of the generated function. * @spec: Specification (&struct ssam_request_spec_md) defining the request. * * Defines a function executing the synchronous SAM request specified by * @spec, with the request having neither argument nor return value. Device * specifying parameters are not hard-coded, but instead must be provided to * the function. The generated function takes care of setting up the request * struct, buffer allocation, as well as execution of the request itself, * returning once the request has been fully completed. The required transport * buffer will be allocated on the stack. * * The generated function is defined as ``static int name(struct * ssam_controller *ctrl, u8 tid, u8 iid)``, returning the status of the * request, which is zero on success and negative on failure. The ``ctrl`` * 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_do_sync_onstack() for more details on the behavior of * the generated function. */#define SSAM_DEFINE_SYNC_REQUEST_MD_N(name, spec...) \ static int name(struct ssam_controller *ctrl, u8 tid, u8 iid) \ { \ struct ssam_request_spec_md s = (struct ssam_request_spec_md)spec; \ struct ssam_request rqst; \ \ rqst.target_category = s.target_category; \ rqst.target_id = tid; \ rqst.command_id = s.command_id; \ rqst.instance_id = iid; \ rqst.flags = s.flags; \ rqst.length = 0; \ rqst.payload = NULL; \ \ return ssam_request_do_sync_onstack(ctrl, &rqst, NULL, 0); \ }
/** * SSAM_DEFINE_SYNC_REQUEST_MD_W() - Define synchronous multi-device SAM * request function with argument. * @name: Name of the generated function. * @atype: Type of the request's argument. * @spec: Specification (&struct ssam_request_spec_md) defining the request. * * Defines a function executing the synchronous SAM request specified by * @spec, with the request taking an argument of type @atype and having no * return value. Device specifying parameters are not hard-coded, but instead * must be provided to the function. The generated function takes care of * setting up the request struct, buffer allocation, as well as execution of * the request itself, returning once the request has been fully completed. * The required transport buffer will be allocated on the stack. * * The generated function is defined as ``static int name(struct * ssam_controller *ctrl, u8 tid, u8 iid, const atype *arg)``, returning the * status of the request, which is zero on success and negative on failure. * The ``ctrl`` parameter is the controller via which the request is sent, * ``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_do_sync_onstack() for more details on the behavior of * the generated function. */#define SSAM_DEFINE_SYNC_REQUEST_MD_W(name, atype, spec...) \ static int name(struct ssam_controller *ctrl, u8 tid, u8 iid, const atype *arg) \ { \ struct ssam_request_spec_md s = (struct ssam_request_spec_md)spec; \ struct ssam_request rqst; \ \ rqst.target_category = s.target_category; \ rqst.target_id = tid; \ rqst.command_id = s.command_id; \ rqst.instance_id = iid; \ rqst.flags = s.flags; \ rqst.length = sizeof(atype); \ rqst.payload = (u8 *)arg; \ \ return ssam_request_do_sync_onstack(ctrl, &rqst, NULL, \ sizeof(atype)); \ }
/** * SSAM_DEFINE_SYNC_REQUEST_MD_R() - Define synchronous multi-device SAM * request function with return value. * @name: Name of the generated function. * @rtype: Type of the request's return value. * @spec: Specification (&struct ssam_request_spec_md) defining the request. * * Defines a function executing the synchronous SAM request specified by * @spec, with the request taking no argument but having a return value of * type @rtype. Device specifying parameters are not hard-coded, but instead * must be provided to the function. The generated function takes care of * setting up the request and response structs, buffer allocation, as well as * execution of the request itself, returning once the request has been fully * completed. The required transport buffer will be allocated on the stack. * * The generated function is defined as ``static int name(struct * ssam_controller *ctrl, u8 tid, u8 iid, rtype *ret)``, returning the status * of the request, which is zero on success and negative on failure. The * ``ctrl`` parameter is the controller via which the request is sent, ``tid`` * 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_do_sync_onstack() for more details on the behavior of * the generated function. */#define SSAM_DEFINE_SYNC_REQUEST_MD_R(name, rtype, spec...) \ static int name(struct ssam_controller *ctrl, u8 tid, u8 iid, rtype *ret) \ { \ struct ssam_request_spec_md s = (struct ssam_request_spec_md)spec; \ struct ssam_request rqst; \ struct ssam_response rsp; \ int status; \ \ rqst.target_category = s.target_category; \ rqst.target_id = tid; \ rqst.command_id = s.command_id; \ rqst.instance_id = iid; \ rqst.flags = s.flags | SSAM_REQUEST_HAS_RESPONSE; \ rqst.length = 0; \ rqst.payload = NULL; \ \ rsp.capacity = sizeof(rtype); \ rsp.length = 0; \ rsp.pointer = (u8 *)ret; \ \ status = ssam_request_do_sync_onstack(ctrl, &rqst, &rsp, 0); \ if (status) \ return status; \ \ if (rsp.length != sizeof(rtype)) { \ struct device *dev = ssam_controller_device(ctrl); \ dev_err(dev, \ "rqst: invalid response length, expected %zu, got %zu (tc: %#04x, cid: %#04x)", \ sizeof(rtype), rsp.length, rqst.target_category,\ rqst.command_id); \ return -EIO; \ } \ \ return 0; \ }
/** * SSAM_DEFINE_SYNC_REQUEST_MD_WR() - Define synchronous multi-device SAM * request function with both argument and return value. * @name: Name of the generated function. * @atype: Type of the request's argument. * @rtype: Type of the request's return value. * @spec: Specification (&struct ssam_request_spec_md) defining the request. * * Defines a function executing the synchronous SAM request specified by @spec, * with the request taking an argument of type @atype and having a return value * of type @rtype. Device specifying parameters are not hard-coded, but instead * must be provided to the function. The generated function takes care of * setting up the request and response structs, buffer allocation, as well as * execution of the request itself, returning once the request has been fully * completed. The required transport buffer will be allocated on the stack. * * The generated function is defined as ``static int name(struct * ssam_controller *ctrl, u8 tid, u8 iid, const atype *arg, rtype *ret)``, * returning the status of the request, which is zero on success and negative * on failure. The ``ctrl`` parameter is the controller via which the request * is sent, ``tid`` the target ID for the request, and ``iid`` the instance ID. * 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_do_sync_onstack() for more details on the behavior of * the generated function. */#define SSAM_DEFINE_SYNC_REQUEST_MD_WR(name, atype, rtype, spec...) \ static int name(struct ssam_controller *ctrl, u8 tid, u8 iid, \ const atype *arg, rtype *ret) \ { \ struct ssam_request_spec_md s = (struct ssam_request_spec_md)spec; \ struct ssam_request rqst; \ struct ssam_response rsp; \ int status; \ \ rqst.target_category = s.target_category; \ rqst.target_id = tid; \ rqst.command_id = s.command_id; \ rqst.instance_id = iid; \ rqst.flags = s.flags | SSAM_REQUEST_HAS_RESPONSE; \ rqst.length = sizeof(atype); \ rqst.payload = (u8 *)arg; \ \ rsp.capacity = sizeof(rtype); \ rsp.length = 0; \ rsp.pointer = (u8 *)ret; \ \ status = ssam_request_do_sync_onstack(ctrl, &rqst, &rsp, sizeof(atype)); \ if (status) \ return status; \ \ if (rsp.length != sizeof(rtype)) { \ struct device *dev = ssam_controller_device(ctrl); \ dev_err(dev, \ "rqst: invalid response length, expected %zu, got %zu (tc: %#04x, cid: %#04x)", \ sizeof(rtype), rsp.length, rqst.target_category,\ rqst.command_id); \ return -EIO; \ } \ \ return 0; \ }
/* -- Event notifier/callbacks. --------------------------------------------- */
#define SSAM_NOTIF_STATE_SHIFT 2#define SSAM_NOTIF_STATE_MASK ((1 << SSAM_NOTIF_STATE_SHIFT) - 1)
/** * enum ssam_notif_flags - Flags used in return values from SSAM notifier * callback functions. * * @SSAM_NOTIF_HANDLED: * Indicates that the notification has been handled. This flag should be * set by the handler if the handler can act/has acted upon the event * provided to it. This flag should not be set if the handler is not a * primary handler intended for the provided event. * * If this flag has not been set by any handler after the notifier chain * has been traversed, a warning will be emitted, stating that the event * has not been handled. * * @SSAM_NOTIF_STOP: * Indicates that the notifier traversal should stop. If this flag is * returned from a notifier callback, notifier chain traversal will * immediately stop and any remaining notifiers will not be called. This * flag is automatically set when ssam_notifier_from_errno() is called * with a negative error value. */enum ssam_notif_flags { SSAM_NOTIF_HANDLED = BIT(0), SSAM_NOTIF_STOP = BIT(1),};
struct ssam_event_notifier;
typedef u32 (*ssam_notifier_fn_t)(struct ssam_event_notifier *nf, const struct ssam_event *event);
/** * struct ssam_notifier_block - Base notifier block for SSAM event * notifications. * @node: The node for the list of notifiers. * @fn: The callback function of this notifier. This function takes the * respective notifier block and event as input and should return * a notifier value, which can either be obtained from the flags * provided in &enum ssam_notif_flags, converted from a standard * error value via ssam_notifier_from_errno(), or a combination of * both (e.g. ``ssam_notifier_from_errno(e) | SSAM_NOTIF_HANDLED``). * @priority: Priority value determining the order in which notifier callbacks * will be called. A higher value means higher priority, i.e. the * associated callback will be executed earlier than other (lower * priority) callbacks. */struct ssam_notifier_block { struct list_head node; ssam_notifier_fn_t fn; int priority;};
/** * ssam_notifier_from_errno() - Convert standard error value to notifier * return code. * @err: The error code to convert, must be negative (in case of failure) or * zero (in case of success). * * Return: Returns the notifier return value obtained by converting the * specified @err value. In case @err is negative, the %SSAM_NOTIF_STOP flag * will be set, causing notifier call chain traversal to abort. */static inline u32 ssam_notifier_from_errno(int err){ if (WARN_ON(err > 0) || err == 0) return 0; else return ((-err) << SSAM_NOTIF_STATE_SHIFT) | SSAM_NOTIF_STOP;}
/** * ssam_notifier_to_errno() - Convert notifier return code to standard error * value. * @ret: The notifier return value to convert. * * Return: Returns the negative error value encoded in @ret or zero if @ret * indicates success. */static inline int ssam_notifier_to_errno(u32 ret){ return -(ret >> SSAM_NOTIF_STATE_SHIFT);}
/* -- Event/notification registry. ------------------------------------------ */
/** * struct ssam_event_registry - Registry specification used for enabling events. * @target_category: Target category for the event registry requests. * @target_id: Target ID for the event registry requests. * @cid_enable: Command ID for the event-enable request. * @cid_disable: Command ID for the event-disable request. * * This struct describes a SAM event registry via the minimal collection of * SAM IDs specifying the requests to use for enabling and disabling an event. * The individual event to be enabled/disabled itself is specified via &struct * ssam_event_id. */struct ssam_event_registry { u8 target_category; u8 target_id; u8 cid_enable; u8 cid_disable;};
/** * struct ssam_event_id - Unique event ID used for enabling events. * @target_category: Target category of the event source. * @instance: Instance ID of the event source. * * This struct specifies the event to be enabled/disabled via an externally * provided registry. It does not specify the registry to be used itself, this * is done via &struct ssam_event_registry. */struct ssam_event_id { u8 target_category; u8 instance;};
/** * enum ssam_event_mask - Flags specifying how events are matched to notifiers. * * @SSAM_EVENT_MASK_NONE: * Run the callback for any event with matching target category. Do not * do any additional filtering. * * @SSAM_EVENT_MASK_TARGET: * In addition to filtering by target category, only execute the notifier * callback for events with a target ID matching to the one of the * registry used for enabling/disabling the event. * * @SSAM_EVENT_MASK_INSTANCE: * In addition to filtering by target category, only execute the notifier * callback for events with an instance ID matching to the instance ID * used when enabling the event. * * @SSAM_EVENT_MASK_STRICT: * Do all the filtering above. */enum ssam_event_mask { SSAM_EVENT_MASK_TARGET = BIT(0), SSAM_EVENT_MASK_INSTANCE = BIT(1),
SSAM_EVENT_MASK_NONE = 0, SSAM_EVENT_MASK_STRICT = SSAM_EVENT_MASK_TARGET | SSAM_EVENT_MASK_INSTANCE,};
/** * SSAM_EVENT_REGISTRY() - Define a new event registry. * @tc: Target category for the event registry requests. * @tid: Target ID for the event registry requests. * @cid_en: Command ID for the event-enable request. * @cid_dis: Command ID for the event-disable request. * * Return: Returns the &struct ssam_event_registry specified by the given * parameters. */#define SSAM_EVENT_REGISTRY(tc, tid, cid_en, cid_dis) \ ((struct ssam_event_registry) { \ .target_category = (tc), \ .target_id = (tid), \ .cid_enable = (cid_en), \ .cid_disable = (cid_dis), \ })
#define SSAM_EVENT_REGISTRY_SAM \ SSAM_EVENT_REGISTRY(SSAM_SSH_TC_SAM, SSAM_SSH_TID_SAM, 0x0b, 0x0c)
#define SSAM_EVENT_REGISTRY_KIP \ SSAM_EVENT_REGISTRY(SSAM_SSH_TC_KIP, SSAM_SSH_TID_KIP, 0x27, 0x28)
#define SSAM_EVENT_REGISTRY_REG(tid)\ SSAM_EVENT_REGISTRY(SSAM_SSH_TC_REG, tid, 0x01, 0x02)
/** * enum ssam_event_notifier_flags - Flags for event notifiers. * @SSAM_EVENT_NOTIFIER_OBSERVER: * The corresponding notifier acts as observer. Registering a notifier * with this flag set will not attempt to enable any event. Equally, * unregistering will not attempt to disable any event. Note that a * notifier with this flag may not even correspond to a certain event at * all, only to a specific event target category. Event matching will not * be influenced by this flag. */enum ssam_event_notifier_flags { SSAM_EVENT_NOTIFIER_OBSERVER = BIT(0),};
/** * struct ssam_event_notifier - Notifier block for SSAM events. * @base: The base notifier block with callback function and priority. * @event: The event for which this block will receive notifications. * @event.reg: Registry via which the event will be enabled/disabled. * @event.id: ID specifying the event. * @event.mask: Flags determining how events are matched to the notifier. * @event.flags: Flags used for enabling the event. * @flags: Notifier flags (see &enum ssam_event_notifier_flags). */struct ssam_event_notifier { struct ssam_notifier_block base;
struct { struct ssam_event_registry reg; struct ssam_event_id id; enum ssam_event_mask mask; u8 flags; } event;
unsigned long flags;};
int ssam_notifier_register(struct ssam_controller *ctrl, struct ssam_event_notifier *n);
int __ssam_notifier_unregister(struct ssam_controller *ctrl, struct ssam_event_notifier *n, bool disable);
/** * ssam_notifier_unregister() - Unregister an event notifier. * @ctrl: The controller the notifier has been registered on. * @n: The event notifier to unregister. * * Unregister an event notifier. Decrement the usage counter of the associated * SAM event if the notifier is not marked as an observer. If the usage counter * reaches zero, the event will be disabled. * * Return: Returns zero on success, %-ENOENT if the given notifier block has * not been registered on the controller. If the given notifier block was the * last one associated with its specific event, returns the status of the * event-disable EC-command. */static inline int ssam_notifier_unregister(struct ssam_controller *ctrl, struct ssam_event_notifier *n){ return __ssam_notifier_unregister(ctrl, n, true);}
int ssam_controller_event_enable(struct ssam_controller *ctrl, struct ssam_event_registry reg, struct ssam_event_id id, u8 flags);
int ssam_controller_event_disable(struct ssam_controller *ctrl, struct ssam_event_registry reg, struct ssam_event_id id, u8 flags);
#endif /* _LINUX_SURFACE_AGGREGATOR_CONTROLLER_H */