Client Driver API Documentation¶
Serial Hub Communication¶
- 
enum ssh_frame_type¶
- Frame types for SSH frames. 
Constants
- SSH_FRAME_TYPE_DATA_SEQ
- Indicates a data frame, followed by a payload with the length specified in the - struct ssh_frame.lenfield. This frame is sequenced, meaning that an ACK is required.
- SSH_FRAME_TYPE_DATA_NSQ
- Same as - SSH_FRAME_TYPE_DATA_SEQ, but unsequenced, meaning that the message does not have to be ACKed.
- SSH_FRAME_TYPE_ACK
- Indicates an ACK message. 
- SSH_FRAME_TYPE_NAK
- Indicates an error response for previously sent frame. In general, this means that the frame and/or payload is malformed, e.g. a CRC is wrong. For command-type payloads, this can also mean that the command is invalid. 
- 
struct ssh_frame¶
- SSH communication frame. 
Definition:
struct ssh_frame {
    u8 type;
    __le16 len;
    u8 seq;
};
Members
- type
- The type of the frame. See - enum ssh_frame_type.
- len
- The length of the frame payload directly following the CRC for this frame. Does not include the final CRC for that payload. 
- seq
- The sequence number for this message/exchange. 
- 
enum ssh_payload_type¶
- Type indicator for the SSH payload. 
Constants
- SSH_PLD_TYPE_CMD
- The payload is a command structure with optional command payload. 
- 
struct ssh_command¶
- Payload of a command-type frame. 
Definition:
struct ssh_command {
    u8 type;
    u8 tc;
    u8 tid;
    u8 sid;
    u8 iid;
    __le16 rqid;
    u8 cid;
};
Members
- type
- The type of the payload. See - enum ssh_payload_type. Should be SSH_PLD_TYPE_CMD for this struct.
- tc
- Command target category. 
- tid
- Target ID. Indicates the target of the message. 
- sid
- Source ID. Indicates the source of the message. 
- iid
- Instance ID. 
- rqid
- Request ID. Used to match requests with responses and differentiate between responses and events. 
- cid
- Command ID. 
- 
SSH_MESSAGE_LENGTH¶
SSH_MESSAGE_LENGTH (payload_size)
Compute length of SSH message.
Parameters
- payload_size
- Length of the payload inside the SSH frame. 
Return
Returns the length of a SSH message with payload of specified size.
- 
SSH_COMMAND_MESSAGE_LENGTH¶
SSH_COMMAND_MESSAGE_LENGTH (payload_size)
Compute length of SSH command message.
Parameters
- payload_size
- Length of the command payload. 
Return
Returns the length of a SSH command message with command payload of specified size.
- 
SSH_MSGOFFSET_FRAME¶
SSH_MSGOFFSET_FRAME (field)
Compute offset in SSH message to specified field in frame.
Parameters
- field
- The field for which the offset should be computed. 
Return
Returns the offset of the specified struct ssh_frame field in the
raw SSH message data as. Takes SYN bytes (u16) preceding the frame into
account.
- 
SSH_MSGOFFSET_COMMAND¶
SSH_MSGOFFSET_COMMAND (field)
Compute offset in SSH message to specified field in command.
Parameters
- field
- The field for which the offset should be computed. 
Return
Returns the offset of the specified struct ssh_command field in
the raw SSH message data. Takes SYN bytes (u16) preceding the frame and the
frame CRC (u16) between frame and command into account.
- 
u16 ssh_crc(const u8 *buf, size_t len)¶
- Compute CRC for SSH messages. 
Parameters
- const u8 *buf
- The pointer pointing to the data for which the CRC should be computed. 
- size_t len
- The length of the data for which the CRC should be computed. 
Return
Returns the CRC computed on the provided data, as used for SSH messages.
- 
u16 ssh_rqid_next_valid(u16 rqid)¶
- Return the next valid request ID. 
Parameters
- u16 rqid
- The current request ID. 
Return
Returns the next valid request ID, following the current request ID provided to this function. This function skips any request IDs reserved for events.
- 
u16 ssh_rqid_to_event(u16 rqid)¶
- Convert request ID to its corresponding event ID. 
Parameters
- u16 rqid
- The request ID to convert. 
- 
bool ssh_rqid_is_event(u16 rqid)¶
- Check if given request ID is a valid event ID. 
Parameters
- u16 rqid
- The request ID to check. 
- 
u16 ssh_tc_to_rqid(u8 tc)¶
- Convert target category to its corresponding request ID. 
Parameters
- u8 tc
- The target category to convert. 
- 
u8 ssh_tid_to_index(u8 tid)¶
- Convert target ID to its corresponding target index. 
Parameters
- u8 tid
- The target ID to convert. 
- 
bool ssh_tid_is_valid(u8 tid)¶
- Check if target ID is valid/supported. 
Parameters
- u8 tid
- The target ID to check. 
- 
struct ssam_span¶
- Reference to a buffer region. 
Definition:
struct ssam_span {
    u8 *ptr;
    size_t len;
};
Members
- ptr
- Pointer to the buffer region. 
- len
- Length of the buffer region. 
Description
A reference to a (non-owned) buffer segment, consisting of pointer and length. Use of this struct indicates non-owned data, i.e. data of which the life-time is managed (i.e. it is allocated/freed) via another pointer.
- 
enum ssam_ssh_tid¶
- Target/source IDs for Serial Hub messages. 
Constants
- SSAM_SSH_TID_HOST
- We as the kernel Serial Hub driver. 
- SSAM_SSH_TID_SAM
- The Surface Aggregator EC. 
- SSAM_SSH_TID_KIP
- Keyboard and perihperal controller. 
- SSAM_SSH_TID_DEBUG
- Debug connector. 
- SSAM_SSH_TID_SURFLINK
- SurfLink connector. 
- 
enum ssh_packet_base_priority¶
- Base priorities for - struct ssh_packet.
Constants
- SSH_PACKET_PRIORITY_FLUSH
- Base priority for flush packets. 
- SSH_PACKET_PRIORITY_DATA
- Base priority for normal data packets. 
- SSH_PACKET_PRIORITY_NAK
- Base priority for NAK packets. 
- SSH_PACKET_PRIORITY_ACK
- Base priority for ACK packets. 
- 
SSH_PACKET_PRIORITY¶
SSH_PACKET_PRIORITY (base, try)
Compute packet priority from base priority and number of tries.
Parameters
- base
- The base priority as suffix of - enum ssh_packet_base_priority, e.g.- FLUSH,- DATA,- ACK, or- NAK.
- try
- The number of tries (must be less than 16). 
Description
Compute the combined packet priority. The combined priority is dominated by the base priority, whereas the number of (re-)tries decides the precedence of packets with the same base priority, giving higher priority to packets that already have more tries.
Return
Returns the computed priority as value fitting inside a u8. A
higher number means a higher priority.
- 
u8 ssh_packet_priority_get_try(u8 priority)¶
- Get number of tries from packet priority. 
Parameters
- u8 priority
- The packet priority. 
Return
Returns the number of tries encoded in the specified packet priority.
- 
u8 ssh_packet_priority_get_base(u8 priority)¶
- Get base priority from packet priority. 
Parameters
- u8 priority
- The packet priority. 
Return
Returns the base priority encoded in the given packet priority.
- 
struct ssh_packet_ops¶
- Callback operations for a SSH packet. 
Definition:
struct ssh_packet_ops {
    void (*release)(struct ssh_packet *p);
    void (*complete)(struct ssh_packet *p, int status);
};
Members
- release
- Function called when the packet reference count reaches zero. This callback must be relied upon to ensure that the packet has left the transport system(s). 
- complete
- Function called when the packet is completed, either with success or failure. In case of failure, the reason for the failure is indicated by the value of the provided status code argument. This value will be zero in case of success. Note that a call to this callback does not guarantee that the packet is not in use by the transport system any more. 
- 
struct ssh_packet¶
- SSH transport packet. 
Definition:
struct ssh_packet {
    struct ssh_ptl *ptl;
    struct kref refcnt;
    u8 priority;
    struct {
        size_t len;
        u8 *ptr;
    } data;
    unsigned long state;
    ktime_t timestamp;
    struct list_head queue_node;
    struct list_head pending_node;
    const struct ssh_packet_ops *ops;
};
Members
- ptl
- Pointer to the packet transport layer. May be - NULLif the packet (or enclosing request) has not been submitted yet.
- refcnt
- Reference count of the packet. 
- priority
- Priority of the packet. Must be computed via - SSH_PACKET_PRIORITY(). Must only be accessed while holding the queue lock after first submission.
- data
- Raw message data. 
- data.len
- Length of the raw message data. 
- data.ptr
- Pointer to the raw message data buffer. 
- state
- State and type flags describing current packet state (dynamic) and type (static). See - enum ssh_packet_flagsfor possible options.
- timestamp
- Timestamp specifying when the latest transmission of a currently pending packet has been started. May be - KTIME_MAXbefore or in-between transmission attempts. Used for the packet timeout implementation. Must only be accessed while holding the pending lock after first submission.
- queue_node
- The list node for the packet queue. 
- pending_node
- The list node for the set of pending packets. 
- ops
- Packet operations. 
- 
void ssh_packet_set_data(struct ssh_packet *p, u8 *ptr, size_t len)¶
- Set raw message data of packet. 
Parameters
- struct ssh_packet *p
- The packet for which the message data should be set. 
- u8 *ptr
- Pointer to the memory holding the message data. 
- size_t len
- Length of the message data. 
Description
Sets the raw message data buffer of the packet to the provided memory. The
memory is not copied. Instead, the caller is responsible for management
(i.e. allocation and deallocation) of the memory. The caller must ensure
that the provided memory is valid and contains a valid SSH message,
starting from the time of submission of the packet until the release
callback has been called. During this time, the memory may not be altered
in any way.
- 
struct ssh_request_ops¶
- Callback operations for a SSH request. 
Definition:
struct ssh_request_ops {
    void (*release)(struct ssh_request *rqst);
    void (*complete)(struct ssh_request *rqst,const struct ssh_command *cmd, const struct ssam_span *data, int status);
};
Members
- release
- Function called when the request’s reference count reaches zero. This callback must be relied upon to ensure that the request has left the transport systems (both, packet an request systems). 
- complete
- Function called when the request is completed, either with success or failure. The command data for the request response is provided via the - struct ssh_commandparameter (- cmd), the command payload of the request response via the- struct ssh_spanparameter (- data).- If the request does not have any response or has not been completed with success, both - cmdand- dataparameters will be NULL. If the request response does not have any command payload, the- dataspan will be an empty (zero-length) span.- In case of failure, the reason for the failure is indicated by the value of the provided status code argument ( - status). This value will be zero in case of success and a regular errno otherwise.- Note that a call to this callback does not guarantee that the request is not in use by the transport systems any more. 
- 
struct ssh_request¶
- SSH transport request. 
Definition:
struct ssh_request {
    struct ssh_packet packet;
    struct list_head node;
    unsigned long state;
    ktime_t timestamp;
    const struct ssh_request_ops *ops;
};
Members
- packet
- The underlying SSH transport packet. 
- node
- List node for the request queue and pending set. 
- state
- State and type flags describing current request state (dynamic) and type (static). See - enum ssh_request_flagsfor possible options.
- timestamp
- Timestamp specifying when we start waiting on the response of the request. This is set once the underlying packet has been completed and may be - KTIME_MAXbefore that, or when the request does not expect a response. Used for the request timeout implementation.
- ops
- Request Operations. 
- 
struct ssh_request *to_ssh_request(struct ssh_packet *p)¶
- Cast a SSH packet to its enclosing SSH request. 
Parameters
- struct ssh_packet *p
- The packet to cast. 
Description
Casts the given struct ssh_packet to its enclosing struct ssh_request.
The caller is responsible for making sure that the packet is actually
wrapped in a struct ssh_request.
Return
Returns the struct ssh_request wrapping the provided packet.
- 
struct ssh_request *ssh_request_get(struct ssh_request *r)¶
- Increment reference count of request. 
Parameters
- struct ssh_request *r
- The request to increment the reference count of. 
Description
Increments the reference count of the given request by incrementing the
reference count of the underlying struct ssh_packet, enclosed in it.
See also ssh_request_put(), ssh_packet_get().
Return
Returns the request provided as input.
- 
void ssh_request_put(struct ssh_request *r)¶
- Decrement reference count of request. 
Parameters
- struct ssh_request *r
- The request to decrement the reference count of. 
Description
Decrements the reference count of the given request by decrementing the
reference count of the underlying struct ssh_packet, enclosed in it. If
the reference count reaches zero, the release callback specified in the
request’s struct ssh_request_ops, i.e. r->ops->release, will be
called.
See also ssh_request_get(), ssh_packet_put().
- 
void ssh_request_set_data(struct ssh_request *r, u8 *ptr, size_t len)¶
- Set raw message data of request. 
Parameters
- struct ssh_request *r
- The request for which the message data should be set. 
- u8 *ptr
- Pointer to the memory holding the message data. 
- size_t len
- Length of the message data. 
Description
Sets the raw message data buffer of the underlying packet to the specified
buffer. Does not copy the actual message data, just sets the buffer pointer
and length. Refer to ssh_packet_set_data() for more details.
- 
struct ssh_packet *ssh_packet_get(struct ssh_packet *packet)¶
- Increment reference count of packet. 
Parameters
- struct ssh_packet *packet
- The packet to increment the reference count of. 
Description
Increments the reference count of the given packet. See ssh_packet_put()
for the counter-part of this function.
Return
Returns the packet provided as input.
- 
void ssh_packet_put(struct ssh_packet *packet)¶
- Decrement reference count of packet. 
Parameters
- struct ssh_packet *packet
- The packet to decrement the reference count of. 
Description
If the reference count reaches zero, the release callback specified in
the packet’s struct ssh_packet_ops, i.e. packet->ops->release, will be
called.
See ssh_packet_get() for the counter-part of this function.
Controller and Core Interface¶
- 
enum ssam_event_flags¶
- Flags for enabling/disabling SAM events 
Constants
- SSAM_EVENT_SEQUENCED
- The event will be sent via a sequenced data frame. 
- 
struct ssam_event¶
- SAM event sent from the EC to the host. 
Definition:
struct ssam_event {
    u8 target_category;
    u8 target_id;
    u8 command_id;
    u8 instance_id;
    u16 length;
    u8 data[] ;
};
Members
- 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. 
- 
enum ssam_request_flags¶
- Flags for SAM requests. 
Constants
- 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_RESPONSEflag are mutually exclusive.
- 
struct ssam_request¶
- SAM request description. 
Definition:
struct ssam_request {
    u8 target_category;
    u8 target_id;
    u8 command_id;
    u8 instance_id;
    u16 flags;
    u16 length;
    const u8 *payload;
};
Members
- 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. 
Description
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_response¶
- Response buffer for SAM request. 
Definition:
struct ssam_response {
    size_t capacity;
    size_t length;
    u8 *pointer;
};
Members
- 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_request_sync¶
- Synchronous SAM request struct. 
Definition:
struct ssam_request_sync {
    struct ssh_request base;
    struct completion comp;
    struct ssam_response *resp;
    int status;
};
Members
- 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. 
- 
void ssam_request_sync_set_data(struct ssam_request_sync *rqst, u8 *ptr, size_t len)¶
- Set message data of a synchronous request. 
Parameters
- struct ssam_request_sync *rqst
- The request. 
- u8 *ptr
- Pointer to the request message data. 
- size_t len
- Length of the request message data. 
Description
Set the request message data of a synchronous request. The provided buffer needs to live until the request has been completed.
- 
void ssam_request_sync_set_resp(struct ssam_request_sync *rqst, struct ssam_response *resp)¶
- Set response buffer of a synchronous request. 
Parameters
- struct ssam_request_sync *rqst
- The request. 
- struct ssam_response *resp
- The response buffer. 
Description
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.
- 
int ssam_request_sync_wait(struct ssam_request_sync *rqst)¶
- Wait for completion of a synchronous request. 
Parameters
- struct ssam_request_sync *rqst
- The request to wait for. 
Description
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.
- 
ssam_request_do_sync_onstack¶
ssam_request_do_sync_onstack (ctrl, rqst, rsp, payload_len)
Execute a synchronous request on the stack.
Parameters
- ctrl
- The controller via which the request is submitted. 
- rqst
- The request specification. 
- rsp
- The response buffer. 
- payload_len
- The (maximum) request payload length. 
Description
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.
- 
__ssam_retry¶
__ssam_retry (request, n, args...)
Retry request in case of I/O errors or timeouts.
Parameters
- request
- The request function to execute. Must return an integer. 
- n
- Number of tries. 
- args...
- Arguments for the request function. 
Description
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.
- 
ssam_retry¶
ssam_retry (request, args...)
Retry request in case of I/O errors or timeouts up to three times in total.
Parameters
- request
- The request function to execute. Must return an integer. 
- args...
- Arguments for the request function. 
Description
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.
- 
struct ssam_request_spec¶
- Blue-print specification of SAM request. 
Definition:
struct ssam_request_spec {
    u8 target_category;
    u8 target_id;
    u8 command_id;
    u8 instance_id;
    u8 flags;
};
Members
- 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.
Description
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_md¶
- Blue-print specification for multi-device SAM request. 
Definition:
struct ssam_request_spec_md {
    u8 target_category;
    u8 command_id;
    u8 flags;
};
Members
- 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.
Description
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.
- 
SSAM_DEFINE_SYNC_REQUEST_N¶
SSAM_DEFINE_SYNC_REQUEST_N (name, spec...)
Define synchronous SAM request function with neither argument nor return value.
Parameters
- name
- Name of the generated function. 
- spec...
- Specification ( - struct ssam_request_spec) defining the request.
Description
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.
- 
SSAM_DEFINE_SYNC_REQUEST_W¶
SSAM_DEFINE_SYNC_REQUEST_W (name, atype, spec...)
Define synchronous SAM request function with argument.
Parameters
- name
- Name of the generated function. 
- atype
- Type of the request’s argument. 
- spec...
- Specification ( - struct ssam_request_spec) defining the request.
Description
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.
- 
SSAM_DEFINE_SYNC_REQUEST_R¶
SSAM_DEFINE_SYNC_REQUEST_R (name, rtype, spec...)
Define synchronous SAM request function with return value.
Parameters
- name
- Name of the generated function. 
- rtype
- Type of the request’s return value. 
- spec...
- Specification ( - struct ssam_request_spec) defining the request.
Description
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.
- 
SSAM_DEFINE_SYNC_REQUEST_WR¶
SSAM_DEFINE_SYNC_REQUEST_WR (name, atype, rtype, spec...)
Define synchronous SAM request function with both argument and return value.
Parameters
- 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.
Description
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.
- 
SSAM_DEFINE_SYNC_REQUEST_MD_N¶
SSAM_DEFINE_SYNC_REQUEST_MD_N (name, spec...)
Define synchronous multi-device SAM request function with neither argument nor return value.
Parameters
- name
- Name of the generated function. 
- spec...
- Specification ( - struct ssam_request_spec_md) defining the request.
Description
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.
- 
SSAM_DEFINE_SYNC_REQUEST_MD_W¶
SSAM_DEFINE_SYNC_REQUEST_MD_W (name, atype, spec...)
Define synchronous multi-device SAM request function with argument.
Parameters
- name
- Name of the generated function. 
- atype
- Type of the request’s argument. 
- spec...
- Specification ( - struct ssam_request_spec_md) defining the request.
Description
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.
- 
SSAM_DEFINE_SYNC_REQUEST_MD_R¶
SSAM_DEFINE_SYNC_REQUEST_MD_R (name, rtype, spec...)
Define synchronous multi-device SAM request function with return value.
Parameters
- name
- Name of the generated function. 
- rtype
- Type of the request’s return value. 
- spec...
- Specification ( - struct ssam_request_spec_md) defining the request.
Description
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.
- 
SSAM_DEFINE_SYNC_REQUEST_MD_WR¶
SSAM_DEFINE_SYNC_REQUEST_MD_WR (name, atype, rtype, spec...)
Define synchronous multi-device SAM request function with both argument and return value.
Parameters
- 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.
Description
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.
- 
enum ssam_notif_flags¶
- Flags used in return values from SSAM notifier callback functions. 
Constants
- 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.
- 
struct ssam_notifier_block¶
- Base notifier block for SSAM event notifications. 
Definition:
struct ssam_notifier_block {
    struct list_head node;
    ssam_notifier_fn_t fn;
    int priority;
};
Members
- 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. 
- 
u32 ssam_notifier_from_errno(int err)¶
- Convert standard error value to notifier return code. 
Parameters
- int 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.
- 
int ssam_notifier_to_errno(u32 ret)¶
- Convert notifier return code to standard error value. 
Parameters
- u32 ret
- The notifier return value to convert. 
Return
Returns the negative error value encoded in ret or zero if ret indicates success.
- 
struct ssam_event_registry¶
- Registry specification used for enabling events. 
Definition:
struct ssam_event_registry {
    u8 target_category;
    u8 target_id;
    u8 cid_enable;
    u8 cid_disable;
};
Members
- 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. 
Description
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_id¶
- Unique event ID used for enabling events. 
Definition:
struct ssam_event_id {
    u8 target_category;
    u8 instance;
};
Members
- target_category
- Target category of the event source. 
- instance
- Instance ID of the event source. 
Description
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.
- 
enum ssam_event_mask¶
- Flags specifying how events are matched to notifiers. 
Constants
- 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_NONE
- Run the callback for any event with matching target category. Do not do any additional filtering. 
- SSAM_EVENT_MASK_STRICT
- Do all the filtering above. 
- 
SSAM_EVENT_REGISTRY¶
SSAM_EVENT_REGISTRY (tc, tid, cid_en, cid_dis)
Define a new event registry.
Parameters
- 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.
- 
enum ssam_event_notifier_flags¶
- Flags for event notifiers. 
Constants
- 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. 
- 
struct ssam_event_notifier¶
- Notifier block for SSAM events. 
Definition:
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;
};
Members
- 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).
- 
int ssam_notifier_unregister(struct ssam_controller *ctrl, struct ssam_event_notifier *n)¶
- Unregister an event notifier. 
Parameters
- struct ssam_controller *ctrl
- The controller the notifier has been registered on. 
- struct ssam_event_notifier *n
- The event notifier to unregister. 
Description
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.
- 
struct device *ssam_controller_device(struct ssam_controller *c)¶
- Get the - struct deviceassociated with this controller.
Parameters
- struct ssam_controller *c
- The controller for which to get the device. 
Return
Returns the struct device associated with this controller,
providing its lower-level transport.
- 
struct ssam_controller *ssam_controller_get(struct ssam_controller *c)¶
- Increment reference count of controller. 
Parameters
- struct ssam_controller *c
- The controller. 
Return
Returns the controller provided as input.
- 
void ssam_controller_put(struct ssam_controller *c)¶
- Decrement reference count of controller. 
Parameters
- struct ssam_controller *c
- The controller. 
- 
void ssam_controller_statelock(struct ssam_controller *c)¶
- Lock the controller against state transitions. 
Parameters
- struct ssam_controller *c
- The controller to lock. 
Description
Lock the controller against state transitions. Holding this lock guarantees that the controller will not transition between states, i.e. if the controller is in state “started”, when this lock has been acquired, it will remain in this state at least until the lock has been released.
Multiple clients may concurrently hold this lock. In other words: The
statelock functions represent the read-lock part of a r/w-semaphore.
Actions causing state transitions of the controller must be executed while
holding the write-part of this r/w-semaphore (see ssam_controller_lock()
and ssam_controller_unlock() for that).
See ssam_controller_stateunlock() for the corresponding unlock function.
- 
void ssam_controller_stateunlock(struct ssam_controller *c)¶
- Unlock controller state transitions. 
Parameters
- struct ssam_controller *c
- The controller to unlock. 
Description
See ssam_controller_statelock() for the corresponding lock function.
- 
ssize_t ssam_request_write_data(struct ssam_span *buf, struct ssam_controller *ctrl, const struct ssam_request *spec)¶
- Construct and write SAM request message to buffer. 
Parameters
- struct ssam_span *buf
- The buffer to write the data to. 
- struct ssam_controller *ctrl
- The controller via which the request will be sent. 
- const struct ssam_request *spec
- The request data and specification. 
Description
Constructs a SAM/SSH request message and writes it to the provided buffer. The request and transport counters, specifically RQID and SEQ, will be set in this call. These counters are obtained from the controller. It is thus only valid to send the resulting message via the controller specified here.
For calculation of the required buffer size, refer to the
SSH_COMMAND_MESSAGE_LENGTH() macro.
Return
Returns the number of bytes used in the buffer on success. Returns
-EINVAL if the payload length provided in the request specification is too
large (larger than SSH_COMMAND_MAX_PAYLOAD_SIZE) or if the provided buffer
is too small.
- 
int ssam_request_sync_alloc(size_t payload_len, gfp_t flags, struct ssam_request_sync **rqst, struct ssam_span *buffer)¶
- Allocate a synchronous request. 
Parameters
- size_t payload_len
- The length of the request payload. 
- gfp_t flags
- Flags used for allocation. 
- struct ssam_request_sync **rqst
- Where to store the pointer to the allocated request. 
- struct ssam_span *buffer
- Where to store the buffer descriptor for the message buffer of the request. 
Description
Allocates a synchronous request with corresponding message buffer. The
request still needs to be initialized ssam_request_sync_init() before
it can be submitted, and the message buffer data must still be set to the
returned buffer via ssam_request_sync_set_data() after it has been filled,
if need be with adjusted message length.
After use, the request and its corresponding message buffer should be freed
via ssam_request_sync_free(). The buffer must not be freed separately.
Return
Returns zero on success, -ENOMEM if the request could not be
allocated.
- 
void ssam_request_sync_free(struct ssam_request_sync *rqst)¶
- Free a synchronous request. 
Parameters
- struct ssam_request_sync *rqst
- The request to be freed. 
Description
Free a synchronous request and its corresponding buffer allocated with
ssam_request_sync_alloc(). Do not use for requests allocated on the stack
or via any other function.
Warning: The caller must ensure that the request is not in use any more.
I.e. the caller must ensure that it has the only reference to the request
and the request is not currently pending. This means that the caller has
either never submitted the request, request submission has failed, or the
caller has waited until the submitted request has been completed via
ssam_request_sync_wait().
- 
int ssam_request_sync_init(struct ssam_request_sync *rqst, enum ssam_request_flags flags)¶
- Initialize a synchronous request struct. 
Parameters
- struct ssam_request_sync *rqst
- The request to initialize. 
- enum ssam_request_flags flags
- The request flags. 
Description
Initializes the given request struct. Does not initialize the request
message data. This has to be done explicitly after this call via
ssam_request_sync_set_data() and the actual message data has to be written
via ssam_request_write_data().
Return
Returns zero on success or -EINVAL if the given flags are invalid.
- 
int ssam_request_sync_submit(struct ssam_controller *ctrl, struct ssam_request_sync *rqst)¶
- Submit a synchronous request. 
Parameters
- struct ssam_controller *ctrl
- The controller with which to submit the request. 
- struct ssam_request_sync *rqst
- The request to submit. 
Description
Submit a synchronous request. The request has to be initialized and
properly set up, including response buffer (may be NULL if no response is
expected) and command message data. This function does not wait for the
request to be completed.
If this function succeeds, ssam_request_sync_wait() must be used to ensure
that the request has been completed before the response data can be
accessed and/or the request can be freed. On failure, the request may
immediately be freed.
This function may only be used if the controller is active, i.e. has been initialized and not suspended.
- 
int ssam_request_do_sync(struct ssam_controller *ctrl, const struct ssam_request *spec, struct ssam_response *rsp)¶
- Execute a synchronous request. 
Parameters
- struct ssam_controller *ctrl
- The controller via which the request will be submitted. 
- const struct ssam_request *spec
- The request specification and payload. 
- struct ssam_response *rsp
- The response buffer. 
Description
Allocates a synchronous request with its message data buffer on the heap
via ssam_request_sync_alloc(), fully initializes it via the provided
request specification, submits it, and finally waits for its completion
before freeing it and returning its status.
Return
Returns the status of the request or any failure during setup.
- 
int ssam_request_do_sync_with_buffer(struct ssam_controller *ctrl, const struct ssam_request *spec, struct ssam_response *rsp, struct ssam_span *buf)¶
- Execute a synchronous request with the provided buffer as back-end for the message buffer. 
Parameters
- struct ssam_controller *ctrl
- The controller via which the request will be submitted. 
- const struct ssam_request *spec
- The request specification and payload. 
- struct ssam_response *rsp
- The response buffer. 
- struct ssam_span *buf
- The buffer for the request message data. 
Description
Allocates a synchronous request struct on the stack, fully initializes it
using the provided buffer as message data buffer, submits it, and then
waits for its completion before returning its status. The
SSH_COMMAND_MESSAGE_LENGTH() macro can be used to compute the required
message buffer size.
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_notifier_register(struct ssam_controller *ctrl, struct ssam_event_notifier *n)¶
- Register an event notifier. 
Parameters
- struct ssam_controller *ctrl
- The controller to register the notifier on. 
- struct ssam_event_notifier *n
- The event notifier to register. 
Description
Register an event notifier. Increment the usage counter of the associated SAM event if the notifier is not marked as an observer. If the event is not marked as an observer and is currently not enabled, it will be enabled during this call. If the notifier is marked as an observer, no attempt will be made at enabling any event and no reference count will be modified.
Notifiers marked as observers do not need to be associated with one specific event, i.e. as long as no event matching is performed, only the event target category needs to be set.
Return
Returns zero on success, -ENOSPC if there have already been
INT_MAX notifiers for the event ID/type associated with the notifier block
registered, -ENOMEM if the corresponding event entry could not be
allocated. If this is the first time that a notifier block is registered
for the specific associated event, returns the status of the event-enable
EC-command.
- 
int __ssam_notifier_unregister(struct ssam_controller *ctrl, struct ssam_event_notifier *n, bool disable)¶
- Unregister an event notifier. 
Parameters
- struct ssam_controller *ctrl
- The controller the notifier has been registered on. 
- struct ssam_event_notifier *n
- The event notifier to unregister. 
- bool disable
- Whether to disable the corresponding event on the EC. 
Description
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 and disable equals true, the event will be disabled.
Useful for hot-removable devices, where communication may fail once the
device has been physically removed. In that case, specifying disable as
false avoids communication with the EC.
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.
- 
int ssam_controller_event_enable(struct ssam_controller *ctrl, struct ssam_event_registry reg, struct ssam_event_id id, u8 flags)¶
- Enable the specified event. 
Parameters
- struct ssam_controller *ctrl
- The controller to enable the event for. 
- struct ssam_event_registry reg
- The event registry to use for enabling the event. 
- struct ssam_event_id id
- The event ID specifying the event to be enabled. 
- u8 flags
- The SAM event flags used for enabling the event. 
Description
Increment the event reference count of the specified event. If the event has not been enabled previously, it will be enabled by this call.
Note
In general, ssam_notifier_register() with a non-observer notifier
should be preferred for enabling/disabling events, as this will guarantee
proper ordering and event forwarding in case of errors during event
enabling/disabling.
Return
Returns zero on success, -ENOSPC if the reference count for the
specified event has reached its maximum, -ENOMEM if the corresponding event
entry could not be allocated. If this is the first time that this event has
been enabled (i.e. the reference count was incremented from zero to one by
this call), returns the status of the event-enable EC-command.
- 
int ssam_controller_event_disable(struct ssam_controller *ctrl, struct ssam_event_registry reg, struct ssam_event_id id, u8 flags)¶
- Disable the specified event. 
Parameters
- struct ssam_controller *ctrl
- The controller to disable the event for. 
- struct ssam_event_registry reg
- The event registry to use for disabling the event. 
- struct ssam_event_id id
- The event ID specifying the event to be disabled. 
- u8 flags
- The flags used when enabling the event. 
Description
Decrement the reference count of the specified event. If the reference count reaches zero, the event will be disabled.
Note
In general, ssam_notifier_register()/ssam_notifier_unregister() with a
non-observer notifier should be preferred for enabling/disabling events, as
this will guarantee proper ordering and event forwarding in case of errors
during event enabling/disabling.
Return
Returns zero on success, -ENOENT if the given event has not been
enabled on the controller. If the reference count of the event reaches zero
during this call, returns the status of the event-disable EC-command.
- 
struct ssam_controller *ssam_get_controller(void)¶
- Get reference to SSAM controller. 
Parameters
- void
- no arguments 
Description
Returns a reference to the SSAM controller of the system or NULL if there
is none, it hasn’t been set up yet, or it has already been unregistered.
This function automatically increments the reference count of the
controller, thus the calling party must ensure that ssam_controller_put()
is called when it doesn’t need the controller any more.
- 
int ssam_client_link(struct ssam_controller *c, struct device *client)¶
- Link an arbitrary client device to the controller. 
Parameters
- struct ssam_controller *c
- The controller to link to. 
- struct device *client
- The client device. 
Description
Link an arbitrary client device to the controller by creating a device link between it as consumer and the controller device as provider. This function can be used for non-SSAM devices (or SSAM devices not registered as child under the controller) to guarantee that the controller is valid for as long as the driver of the client device is bound, and that proper suspend and resume ordering is guaranteed.
The device link does not have to be destructed manually. It is removed automatically once the driver of the client device unbinds.
Return
Returns zero on success, -ENODEV if the controller is not ready or
going to be removed soon, or -ENOMEM if the device link could not be
created for other reasons.
- 
struct ssam_controller *ssam_client_bind(struct device *client)¶
- Bind an arbitrary client device to the controller. 
Parameters
- struct device *client
- The client device. 
Description
Link an arbitrary client device to the controller by creating a device link between it as consumer and the main controller device as provider. This function can be used for non-SSAM devices to guarantee that the controller returned by this function is valid for as long as the driver of the client device is bound, and that proper suspend and resume ordering is guaranteed.
This function does essentially the same as ssam_client_link(), except that
it first fetches the main controller reference, then creates the link, and
finally returns this reference. Note that this function does not increment
the reference counter of the controller, as, due to the link, the
controller lifetime is assured as long as the driver of the client device
is bound.
It is not valid to use the controller reference obtained by this method
outside of the driver bound to the client device at the time of calling
this function, without first incrementing the reference count of the
controller via ssam_controller_get(). Even after doing this, care must be
taken that requests are only submitted and notifiers are only
(un-)registered when the controller is active and not suspended. In other
words: The device link only lives as long as the client driver is bound and
any guarantees enforced by this link (e.g. active controller state) can
only be relied upon as long as this link exists and may need to be enforced
in other ways afterwards.
The created device link does not have to be destructed manually. It is removed automatically once the driver of the client device unbinds.
Return
Returns the controller on success, an error pointer with -ENODEV
if the controller is not present, not ready or going to be removed soon, or
-ENOMEM if the device link could not be created for other reasons.
Client Bus and Client Device API¶
- 
enum ssam_device_domain¶
- SAM device domain. 
Constants
- SSAM_DOMAIN_VIRTUAL
- Virtual device. 
- SSAM_DOMAIN_SERIALHUB
- Physical device connected via Surface Serial Hub. 
- 
enum ssam_virtual_tc¶
- Target categories for the virtual SAM domain. 
Constants
- SSAM_VIRTUAL_TC_HUB
- Device hub category. 
- 
struct ssam_device_uid¶
- Unique identifier for SSAM device. 
Definition:
struct ssam_device_uid {
    u8 domain;
    u8 category;
    u8 target;
    u8 instance;
    u8 function;
};
Members
- domain
- Domain of the device. 
- category
- Target category of the device. 
- target
- Target ID of the device. 
- instance
- Instance ID of the device. 
- function
- Sub-function of the device. This field can be used to split a single SAM device into multiple virtual subdevices to separate different functionality of that device and allow one driver per such functionality. 
- 
SSAM_DEVICE¶
SSAM_DEVICE (d, cat, tid, iid, fun)
Initialize a
struct ssam_device_idwith the given parameters.
Parameters
- d
- Domain of the device. 
- cat
- Target category of the device. 
- tid
- Target ID of the device. 
- iid
- Instance ID of the device. 
- fun
- Sub-function of the device. 
Description
Initializes a struct ssam_device_id with the given parameters. See struct
ssam_device_uid for details regarding the parameters. The special values
SSAM_SSH_TID_ANY, SSAM_SSH_IID_ANY, and SSAM_SSH_FUN_ANY can be used to specify that
matching should ignore target ID, instance ID, and/or sub-function,
respectively. This macro initializes the match_flags field based on the
given parameters.
Note
The parameters d and cat must be valid u8 values, the parameters
tid, iid, and fun must be either valid u8 values or SSAM_SSH_TID_ANY,
SSAM_SSH_IID_ANY, or SSAM_SSH_FUN_ANY, respectively. Other non-u8 values are not
allowed.
- 
SSAM_VDEV¶
SSAM_VDEV (cat, tid, iid, fun)
Initialize a
struct ssam_device_idas virtual device with the given parameters.
Parameters
- cat
- Target category of the device. 
- tid
- Target ID of the device. 
- iid
- Instance ID of the device. 
- fun
- Sub-function of the device. 
Description
Initializes a struct ssam_device_id with the given parameters in the
virtual domain. See struct ssam_device_uid for details regarding the
parameters. The special values SSAM_SSH_TID_ANY, SSAM_SSH_IID_ANY, and
SSAM_SSH_FUN_ANY can be used to specify that matching should ignore target ID,
instance ID, and/or sub-function, respectively. This macro initializes the
match_flags field based on the given parameters.
Note
The parameter cat must be a valid u8 value, the parameters tid,
iid, and fun must be either valid u8 values or SSAM_SSH_TID_ANY,
SSAM_SSH_IID_ANY, or SSAM_SSH_FUN_ANY, respectively. Other non-u8 values are not
allowed.
- 
SSAM_SDEV¶
SSAM_SDEV (cat, tid, iid, fun)
Initialize a
struct ssam_device_idas physical SSH device with the given parameters.
Parameters
- cat
- Target category of the device. 
- tid
- Target ID of the device. 
- iid
- Instance ID of the device. 
- fun
- Sub-function of the device. 
Description
Initializes a struct ssam_device_id with the given parameters in the SSH
domain. See struct ssam_device_uid for details regarding the parameters.
The special values SSAM_SSH_TID_ANY, SSAM_SSH_IID_ANY, and
SSAM_SSH_FUN_ANY can be used to specify that matching should ignore target
ID, instance ID, and/or sub-function, respectively. This macro initializes
the match_flags field based on the given parameters.
Note
The parameter cat must be a valid u8 value, the parameters tid,
iid, and fun must be either valid u8 values or SSAM_SSH_TID_ANY,
SSAM_SSH_IID_ANY, or SSAM_SSH_FUN_ANY, respectively. Other non-u8 values
are not allowed.
- 
struct ssam_device¶
- SSAM client device. 
Definition:
struct ssam_device {
    struct device dev;
    struct ssam_controller *ctrl;
    struct ssam_device_uid uid;
    unsigned long flags;
};
Members
- dev
- Driver model representation of the device. 
- ctrl
- SSAM controller managing this device. 
- uid
- UID identifying the device. 
- flags
- Device state flags, see - enum ssam_device_flags.
- 
struct ssam_device_driver¶
- SSAM client device driver. 
Definition:
struct ssam_device_driver {
    struct device_driver driver;
    const struct ssam_device_id *match_table;
    int (*probe)(struct ssam_device *sdev);
    void (*remove)(struct ssam_device *sdev);
};
Members
- driver
- Base driver model structure. 
- match_table
- Match table specifying which devices the driver should bind to. 
- probe
- Called when the driver is being bound to a device. 
- remove
- Called when the driver is being unbound from the device. 
Parameters
- struct device *d
- The device to test the type of. 
Return
Returns true if the specified device is of type struct
ssam_device, i.e. the device type points to ssam_device_type, and false
otherwise.
- 
to_ssam_device¶
to_ssam_device (d)
Casts the given device to a SSAM client device.
Parameters
- d
- The device to cast. 
Description
Casts the given struct device to a struct ssam_device. The caller has to
ensure that the given device is actually enclosed in a struct ssam_device,
e.g. by calling is_ssam_device().
Return
Returns a pointer to the struct ssam_device wrapping the given
device d.
- 
to_ssam_device_driver¶
to_ssam_device_driver (d)
Casts the given device driver to a SSAM client device driver.
Parameters
- d
- The driver to cast. 
Description
Casts the given struct device_driver to a struct ssam_device_driver. The
caller has to ensure that the given driver is actually enclosed in a
struct ssam_device_driver.
Return
Returns the pointer to the struct ssam_device_driver wrapping the
given device driver d.
- 
void ssam_device_mark_hot_removed(struct ssam_device *sdev)¶
- Mark the given device as hot-removed. 
Parameters
- struct ssam_device *sdev
- The device to mark as hot-removed. 
Description
Mark the device as having been hot-removed. This signals drivers using the device that communication with the device should be avoided and may lead to timeouts.
- 
bool ssam_device_is_hot_removed(struct ssam_device *sdev)¶
- Check if the given device has been hot-removed. 
Parameters
- struct ssam_device *sdev
- The device to check. 
Description
Checks if the given device has been marked as hot-removed. See
ssam_device_mark_hot_removed() for more details.
Return
Returns true if the device has been marked as hot-removed.
- 
struct ssam_device *ssam_device_get(struct ssam_device *sdev)¶
- Increment reference count of SSAM client device. 
Parameters
- struct ssam_device *sdev
- The device to increment the reference count of. 
Description
Increments the reference count of the given SSAM client device by
incrementing the reference count of the enclosed struct device via
get_device().
See ssam_device_put() for the counter-part of this function.
Return
Returns the device provided as input.
- 
void ssam_device_put(struct ssam_device *sdev)¶
- Decrement reference count of SSAM client device. 
Parameters
- struct ssam_device *sdev
- The device to decrement the reference count of. 
Description
Decrements the reference count of the given SSAM client device by
decrementing the reference count of the enclosed struct device via
put_device().
See ssam_device_get() for the counter-part of this function.
- 
void *ssam_device_get_drvdata(struct ssam_device *sdev)¶
- Get driver-data of SSAM client device. 
Parameters
- struct ssam_device *sdev
- The device to get the driver-data from. 
Return
Returns the driver-data of the given device, previously set via
ssam_device_set_drvdata().
- 
void ssam_device_set_drvdata(struct ssam_device *sdev, void *data)¶
- Set driver-data of SSAM client device. 
Parameters
- struct ssam_device *sdev
- The device to set the driver-data of. 
- void *data
- The data to set the device’s driver-data pointer to. 
- 
ssam_device_driver_register¶
ssam_device_driver_register (drv)
Register a SSAM client device driver.
Parameters
- drv
- The driver to register. 
- 
module_ssam_device_driver¶
module_ssam_device_driver (drv)
Helper macro for SSAM device driver registration.
Parameters
- drv
- The driver managed by this module. 
Description
Helper macro to register a SSAM device driver via module_init() and
module_exit(). This macro may only be used once per module and replaces the
aforementioned definitions.
- 
int ssam_register_clients(struct device *dev, struct ssam_controller *ctrl)¶
- Register all client devices defined under the given parent device. 
Parameters
- struct device *dev
- The parent device under which clients should be registered. 
- struct ssam_controller *ctrl
- The controller with which client should be registered. 
Description
Register all clients that have via firmware nodes been defined as children of the given (parent) device. The respective child firmware nodes will be associated with the correspondingly created child devices.
The given controller will be used to instantiate the new devices. See
ssam_device_add() for details.
Return
Returns zero on success, nonzero on failure.
- 
int ssam_device_register_clients(struct ssam_device *sdev)¶
- Register all client devices defined under the given SSAM parent device. 
Parameters
- struct ssam_device *sdev
- The parent device under which clients should be registered. 
Description
Register all clients that have via firmware nodes been defined as children of the given (parent) device. The respective child firmware nodes will be associated with the correspondingly created child devices.
The controller used by the parent device will be used to instantiate the new
devices. See ssam_device_add() for details.
Return
Returns zero on success, nonzero on failure.
- 
SSAM_DEFINE_SYNC_REQUEST_CL_N¶
SSAM_DEFINE_SYNC_REQUEST_CL_N (name, spec...)
Define synchronous client-device SAM request function with neither argument nor return value.
Parameters
- name
- Name of the generated function. 
- spec...
- Specification ( - struct ssam_request_spec_md) defining the request.
Description
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 are provided via the client device, specifically its UID, supplied when calling this 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_device
*sdev), returning the status of the request, which is zero on success and
negative on failure. The sdev parameter specifies both the target
device of the request and by association the controller via which the
request is sent.
Refer to ssam_request_do_sync_onstack() for more details on the behavior of
the generated function.
- 
SSAM_DEFINE_SYNC_REQUEST_CL_W¶
SSAM_DEFINE_SYNC_REQUEST_CL_W (name, atype, spec...)
Define synchronous client-device SAM request function with argument.
Parameters
- name
- Name of the generated function. 
- atype
- Type of the request’s argument. 
- spec...
- Specification ( - struct ssam_request_spec_md) defining the request.
Description
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 are provided via the client device, specifically its UID, supplied when calling this 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_device
*sdev, const atype *arg), returning the status of the request, which is
zero on success and negative on failure. The sdev parameter specifies
both the target device of the request and by association the controller via
which the request is sent. The request’s argument is specified via the
arg pointer.
Refer to ssam_request_do_sync_onstack() for more details on the behavior of
the generated function.
- 
SSAM_DEFINE_SYNC_REQUEST_CL_R¶
SSAM_DEFINE_SYNC_REQUEST_CL_R (name, rtype, spec...)
Define synchronous client-device SAM request function with return value.
Parameters
- name
- Name of the generated function. 
- rtype
- Type of the request’s return value. 
- spec...
- Specification ( - struct ssam_request_spec_md) defining the request.
Description
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 are provided via the client device, specifically its UID, supplied when calling this 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_device
*sdev, rtype *ret), returning the status of the request, which is zero on
success and negative on failure. The sdev parameter specifies both the
target device of the request and by association 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.
- 
SSAM_DEFINE_SYNC_REQUEST_CL_WR¶
SSAM_DEFINE_SYNC_REQUEST_CL_WR (name, atype, rtype, spec...)
Define synchronous client-device SAM request function with argument and return value.
Parameters
- 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.
Description
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 are provided via the client device, specifically its UID, supplied when calling this 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_device
*sdev, const atype *arg, rtype *ret), returning the status of the request,
which is zero on success and negative on failure. The sdev parameter
specifies both the target device of the request and by association the
controller via which the request is sent. The request’s 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.
- 
int ssam_device_notifier_register(struct ssam_device *sdev, struct ssam_event_notifier *n)¶
- Register an event notifier for the specified client device. 
Parameters
- struct ssam_device *sdev
- The device the notifier should be registered on. 
- struct ssam_event_notifier *n
- The event notifier to register. 
Description
Register an event notifier. Increment the usage counter of the associated SAM event if the notifier is not marked as an observer. If the event is not marked as an observer and is currently not enabled, it will be enabled during this call. If the notifier is marked as an observer, no attempt will be made at enabling any event and no reference count will be modified.
Notifiers marked as observers do not need to be associated with one specific event, i.e. as long as no event matching is performed, only the event target category needs to be set.
Return
Returns zero on success, -ENOSPC if there have already been
INT_MAX notifiers for the event ID/type associated with the notifier block
registered, -ENOMEM if the corresponding event entry could not be
allocated, -ENODEV if the device is marked as hot-removed. If this is the
first time that a notifier block is registered for the specific associated
event, returns the status of the event-enable EC-command.
- 
int ssam_device_notifier_unregister(struct ssam_device *sdev, struct ssam_event_notifier *n)¶
- Unregister an event notifier for the specified client device. 
Parameters
- struct ssam_device *sdev
- The device the notifier has been registered on. 
- struct ssam_event_notifier *n
- The event notifier to unregister. 
Description
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.
In case the device has been marked as hot-removed, the event will not be disabled on the EC, as in those cases any attempt at doing so may time out.
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.
- 
struct ssam_device *ssam_device_alloc(struct ssam_controller *ctrl, struct ssam_device_uid uid)¶
- Allocate and initialize a SSAM client device. 
Parameters
- struct ssam_controller *ctrl
- The controller under which the device should be added. 
- struct ssam_device_uid uid
- The UID of the device to be added. 
Description
Allocates and initializes a new client device. The parent of the device
will be set to the controller device and the name will be set based on the
UID. Note that the device still has to be added via ssam_device_add().
Refer to that function for more details.
Return
Returns the newly allocated and initialized SSAM client device, or
NULL if it could not be allocated.
- 
int ssam_device_add(struct ssam_device *sdev)¶
- Add a SSAM client device. 
Parameters
- struct ssam_device *sdev
- The SSAM client device to be added. 
Description
Added client devices must be guaranteed to always have a valid and active
controller. Thus, this function will fail with -ENODEV if the controller
of the device has not been initialized yet, has been suspended, or has been
shut down.
The caller of this function should ensure that the corresponding call to
ssam_device_remove() is issued before the controller is shut down. If the
added device is a direct child of the controller device (default), it will
be automatically removed when the controller is shut down.
By default, the controller device will become the parent of the newly
created client device. The parent may be changed before ssam_device_add is
called, but care must be taken that a) the correct suspend/resume ordering
is guaranteed and b) the client device does not outlive the controller,
i.e. that the device is removed before the controller is being shut down.
In case these guarantees have to be manually enforced, please refer to the
ssam_client_link() and ssam_client_bind() functions, which are intended to
set up device-links for this purpose.
Return
Returns zero on success, a negative error code on failure.
- 
void ssam_device_remove(struct ssam_device *sdev)¶
- Remove a SSAM client device. 
Parameters
- struct ssam_device *sdev
- The device to remove. 
Description
Removes and unregisters the provided SSAM client device.
- 
const struct ssam_device_id *ssam_device_id_match(const struct ssam_device_id *table, const struct ssam_device_uid uid)¶
- Find the matching ID table entry for the given UID. 
Parameters
- const struct ssam_device_id *table
- The table to search in. 
- const struct ssam_device_uid uid
- The UID to matched against the individual table entries. 
Description
Find the first match for the provided device UID in the provided ID table
and return it. Returns NULL if no match could be found.
- 
const struct ssam_device_id *ssam_device_get_match(const struct ssam_device *dev)¶
- Find and return the ID matching the device in the ID table of the bound driver. 
Parameters
- const struct ssam_device *dev
- The device for which to get the matching ID table entry. 
Description
Find the fist match for the UID of the device in the ID table of the
currently bound driver and return it. Returns NULL if the device does not
have a driver bound to it, the driver does not have match_table (i.e. it is
NULL), or there is no match in the driver’s match_table.
This function essentially calls ssam_device_id_match() with the ID table of
the bound device driver and the UID of the device.
Return
Returns the first match for the UID of the device in the device
driver’s match table, or NULL if no such match could be found.
- 
const void *ssam_device_get_match_data(const struct ssam_device *dev)¶
- Find the ID matching the device in the ID table of the bound driver and return its - driver_datamember.
Parameters
- const struct ssam_device *dev
- The device for which to get the match data. 
Description
Find the fist match for the UID of the device in the ID table of the
corresponding driver and return its driver_data. Returns NULL if the
device does not have a driver bound to it, the driver does not have
match_table (i.e. it is NULL), there is no match in the driver’s
match_table, or the match does not have any driver_data.
This function essentially calls ssam_device_get_match() and, if any match
could be found, returns its struct ssam_device_id.driver_data member.
Return
Returns the driver data associated with the first match for the UID
of the device in the device driver’s match table, or NULL if no such match
could be found.
- 
int __ssam_device_driver_register(struct ssam_device_driver *sdrv, struct module *owner)¶
- Register a SSAM client device driver. 
Parameters
- struct ssam_device_driver *sdrv
- The driver to register. 
- struct module *owner
- The module owning the provided driver. 
Description
Please refer to the ssam_device_driver_register() macro for the normal way
to register a driver from inside its owning module.
- 
void ssam_device_driver_unregister(struct ssam_device_driver *sdrv)¶
- Unregister a SSAM device driver. 
Parameters
- struct ssam_device_driver *sdrv
- The driver to unregister. 
- 
int __ssam_register_clients(struct device *parent, struct ssam_controller *ctrl, struct fwnode_handle *node)¶
- Register client devices defined under the given firmware node as children of the given device. 
Parameters
- struct device *parent
- The parent device under which clients should be registered. 
- struct ssam_controller *ctrl
- The controller with which client should be registered. 
- struct fwnode_handle *node
- The firmware node holding definitions of the devices to be added. 
Description
Register all clients that have been defined as children of the given root firmware node as children of the given parent device. The respective child firmware nodes will be associated with the correspondingly created child devices.
The given controller will be used to instantiate the new devices. See
ssam_device_add() for details.
Note that, generally, the use of either ssam_device_register_clients() or
ssam_register_clients() should be preferred as they directly use the
firmware node and/or controller associated with the given device. This
function is only intended for use when different device specifications (e.g.
ACPI and firmware nodes) need to be combined (as is done in the platform hub
of the device registry).
Return
Returns zero on success, nonzero on failure.
- 
void ssam_remove_clients(struct device *dev)¶
- Remove SSAM client devices registered as direct children under the given parent device. 
Parameters
- struct device *dev
- The (parent) device to remove all direct clients for. 
Description
Remove all SSAM client devices registered as direct children under the given
device. Note that this only accounts for direct children of the device.
Refer to ssam_device_add()/ssam_device_remove() for more details.