1/* SPDX-License-Identifier: GPL-2.0 */
2/*
3 * System Control and Management Interface (SCMI) Message Protocol
4 * notification header file containing some definitions, structures
5 * and function prototypes related to SCMI Notification handling.
6 *
7 * Copyright (C) 2020-2021 ARM Ltd.
8 */
9#ifndef _SCMI_NOTIFY_H
10#define _SCMI_NOTIFY_H
11
12#include <linux/device.h>
13#include <linux/ktime.h>
14#include <linux/types.h>
15
16#define SCMI_PROTO_QUEUE_SZ	4096
17
18/**
19 * struct scmi_event  - Describes an event to be supported
20 * @id: Event ID
21 * @max_payld_sz: Max possible size for the payload of a notification message
22 * @max_report_sz: Max possible size for the report of a notification message
23 *
24 * Each SCMI protocol, during its initialization phase, can describe the events
25 * it wishes to support in a few struct scmi_event and pass them to the core
26 * using scmi_register_protocol_events().
27 */
28struct scmi_event {
29	u8	id;
30	size_t	max_payld_sz;
31	size_t	max_report_sz;
32};
33
34struct scmi_protocol_handle;
35
36/**
37 * struct scmi_event_ops  - Protocol helpers called by the notification core.
38 * @is_notify_supported: Return 0 if the specified notification for the
39 *			 specified resource (src_id) is supported.
40 * @get_num_sources: Returns the number of possible events' sources for this
41 *		     protocol
42 * @set_notify_enabled: Enable/disable the required evt_id/src_id notifications
43 *			using the proper custom protocol commands.
44 *			Return 0 on Success
45 * @fill_custom_report: fills a custom event report from the provided
46 *			event message payld identifying the event
47 *			specific src_id.
48 *			Return NULL on failure otherwise @report now fully
49 *			populated
50 *
51 * Context: Helpers described in &struct scmi_event_ops are called only in
52 *	    process context.
53 */
54struct scmi_event_ops {
55	bool (*is_notify_supported)(const struct scmi_protocol_handle *ph,
56				    u8 evt_id, u32 src_id);
57	int (*get_num_sources)(const struct scmi_protocol_handle *ph);
58	int (*set_notify_enabled)(const struct scmi_protocol_handle *ph,
59				  u8 evt_id, u32 src_id, bool enabled);
60	void *(*fill_custom_report)(const struct scmi_protocol_handle *ph,
61				    u8 evt_id, ktime_t timestamp,
62				    const void *payld, size_t payld_sz,
63				    void *report, u32 *src_id);
64};
65
66/**
67 * struct scmi_protocol_events  - Per-protocol description of available events
68 * @queue_sz: Size in bytes of the per-protocol queue to use.
69 * @ops: Array of protocol-specific events operations.
70 * @evts: Array of supported protocol's events.
71 * @num_events: Number of supported protocol's events described in @evts.
72 * @num_sources: Number of protocol's sources, should be greater than 0; if not
73 *		 available at compile time, it will be provided at run-time via
74 *		 @get_num_sources.
75 */
76struct scmi_protocol_events {
77	size_t				queue_sz;
78	const struct scmi_event_ops	*ops;
79	const struct scmi_event		*evts;
80	unsigned int			num_events;
81	unsigned int			num_sources;
82};
83
84int scmi_notification_init(struct scmi_handle *handle);
85void scmi_notification_exit(struct scmi_handle *handle);
86int scmi_register_protocol_events(const struct scmi_handle *handle, u8 proto_id,
87				  const struct scmi_protocol_handle *ph,
88				  const struct scmi_protocol_events *ee);
89void scmi_deregister_protocol_events(const struct scmi_handle *handle,
90				     u8 proto_id);
91int scmi_notify(const struct scmi_handle *handle, u8 proto_id, u8 evt_id,
92		const void *buf, size_t len, ktime_t ts);
93
94#endif /* _SCMI_NOTIFY_H */
95