From: Stephen Warren Date: Fri, 17 Jun 2016 15:43:56 +0000 (-0600) Subject: mailbox: rename headers X-Git-Tag: v2016.07-rc2~5^2~4 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=769d52ef0f04812fd65ef2f3ab921ad2e8562ab1;p=u-boot mailbox: rename headers Rename mailbox*.h to match the naming convention requested during review of the new reset subsystem. Signed-off-by: Stephen Warren Acked-by: Simon Glass --- diff --git a/drivers/mailbox/mailbox-uclass.c b/drivers/mailbox/mailbox-uclass.c index 73fa32874a..40f851d915 100644 --- a/drivers/mailbox/mailbox-uclass.c +++ b/drivers/mailbox/mailbox-uclass.c @@ -7,8 +7,8 @@ #include #include #include -#include -#include +#include +#include DECLARE_GLOBAL_DATA_PTR; diff --git a/drivers/mailbox/sandbox-mbox-test.c b/drivers/mailbox/sandbox-mbox-test.c index 02d161aada..8351522bd4 100644 --- a/drivers/mailbox/sandbox-mbox-test.c +++ b/drivers/mailbox/sandbox-mbox-test.c @@ -6,7 +6,7 @@ #include #include -#include +#include #include struct sandbox_mbox_test { diff --git a/drivers/mailbox/sandbox-mbox.c b/drivers/mailbox/sandbox-mbox.c index 1b7ac231cb..530c62c029 100644 --- a/drivers/mailbox/sandbox-mbox.c +++ b/drivers/mailbox/sandbox-mbox.c @@ -6,7 +6,7 @@ #include #include -#include +#include #include #include diff --git a/include/mailbox-uclass.h b/include/mailbox-uclass.h new file mode 100644 index 0000000000..6ec62e5a0e --- /dev/null +++ b/include/mailbox-uclass.h @@ -0,0 +1,83 @@ +/* + * Copyright (c) 2016, NVIDIA CORPORATION. + * + * SPDX-License-Identifier: GPL-2.0 + */ + +#ifndef _MAILBOX_UCLASS_H +#define _MAILBOX_UCLASS_H + +/* See mailbox.h for background documentation. */ + +#include + +struct udevice; + +/** + * struct mbox_ops - The functions that a mailbox driver must implement. + */ +struct mbox_ops { + /** + * of_xlate - Translate a client's device-tree (OF) mailbox specifier. + * + * The mailbox core calls this function as the first step in + * implementing a client's mbox_get_by_*() call. + * + * If this function pointer is set to NULL, the mailbox core will use + * a default implementation, which assumes #mbox-cells = <1>, and that + * the DT cell contains a simple integer channel ID. + * + * At present, the mailbox API solely supports device-tree. If this + * changes, other xxx_xlate() functions may be added to support those + * other mechanisms. + * + * @chan: The channel to hold the translation result. + * @args: The mailbox specifier values from device tree. + * @return 0 if OK, or a negative error code. + */ + int (*of_xlate)(struct mbox_chan *chan, + struct fdtdec_phandle_args *args); + /** + * request - Request a translated channel. + * + * The mailbox core calls this function as the second step in + * implementing a client's mbox_get_by_*() call, following a successful + * xxx_xlate() call. + * + * @chan: The channel to request; this has been filled in by a + * previoux xxx_xlate() function call. + * @return 0 if OK, or a negative error code. + */ + int (*request)(struct mbox_chan *chan); + /** + * free - Free a previously requested channel. + * + * This is the implementation of the client mbox_free() API. + * + * @chan: The channel to free. + * @return 0 if OK, or a negative error code. + */ + int (*free)(struct mbox_chan *chan); + /** + * send - Send a message over a mailbox channel + * + * @chan: The channel to send to the message to. + * @data: A pointer to the message to send. + * @return 0 if OK, or a negative error code. + */ + int (*send)(struct mbox_chan *chan, const void *data); + /** + * recv - Receive any available message from the channel. + * + * This function does not block. If not message is immediately + * available, the function should return an error. + * + * @chan: The channel to receive to the message from. + * @data: A pointer to the buffer to hold the received message. + * @return 0 if OK, -ENODATA if no message was available, or a negative + * error code. + */ + int (*recv)(struct mbox_chan *chan, void *data); +}; + +#endif diff --git a/include/mailbox.h b/include/mailbox.h new file mode 100644 index 0000000000..a92a1a590d --- /dev/null +++ b/include/mailbox.h @@ -0,0 +1,149 @@ +/* + * Copyright (c) 2016, NVIDIA CORPORATION. + * + * SPDX-License-Identifier: GPL-2.0 + */ + +#ifndef _MAILBOX_H +#define _MAILBOX_H + +/** + * A mailbox is a hardware mechanism for transferring small fixed-size messages + * and/or notifications between the CPU on which U-Boot runs and some other + * device such as an auxiliary CPU running firmware or a hardware module. + * + * Data transfer is optional; a mailbox may consist solely of a notification + * mechanism. When data transfer is implemented, it is via HW registers or + * FIFOs, rather than via RAM-based buffers. The mailbox API generally + * implements any communication protocol enforced solely by hardware, and + * leaves any higher-level protocols to other layers. + * + * A mailbox channel is a bi-directional mechanism that can send a message or + * notification to a single specific remote entity, and receive messages or + * notifications from that entity. The size, content, and format of such + * messages is defined by the mailbox implementation, or the remote entity with + * which it communicates; there is no general standard at this API level. + * + * A driver that implements UCLASS_MAILBOX is a mailbox provider. A provider + * will often implement multiple separate mailbox channels, since the hardware + * it manages often has this capability. mailbox-uclass.h describes the + * interface which mailbox providers must implement. + * + * Mailbox consumers/clients generate and send, or receive and process, + * messages. This header file describes the API used by clients. + */ + +struct udevice; + +/** + * struct mbox_chan - A handle to a single mailbox channel. + * + * Clients provide storage for channels. The content of the channel structure + * is managed solely by the mailbox API and mailbox drivers. A mailbox channel + * is initialized by "get"ing the mailbox. The channel struct is passed to all + * other mailbox APIs to identify which mailbox to operate upon. + * + * @dev: The device which implements the mailbox. + * @id: The mailbox channel ID within the provider. + * + * Currently, the mailbox API assumes that a single integer ID is enough to + * identify and configure any mailbox channel for any mailbox provider. If this + * assumption becomes invalid in the future, the struct could be expanded to + * either (a) add more fields to allow mailbox providers to store additional + * information, or (b) replace the id field with an opaque pointer, which the + * provider would dynamically allocated during its .of_xlate op, and process + * during is .request op. This may require the addition of an extra op to clean + * up the allocation. + */ +struct mbox_chan { + struct udevice *dev; + /* + * Written by of_xlate. We assume a single id is enough for now. In the + * future, we might add more fields here. + */ + unsigned long id; +}; + +/** + * mbox_get_by_index - Get/request a mailbox by integer index + * + * This looks up and requests a mailbox channel. The index is relative to the + * client device; each device is assumed to have n mailbox channels associated + * with it somehow, and this function finds and requests one of them. The + * mapping of client device channel indices to provider channels may be via + * device-tree properties, board-provided mapping tables, or some other + * mechanism. + * + * @dev: The client device. + * @index: The index of the mailbox channel to request, within the + * client's list of channels. + * @chan A pointer to a channel object to initialize. + * @return 0 if OK, or a negative error code. + */ +int mbox_get_by_index(struct udevice *dev, int index, struct mbox_chan *chan); + +/** + * mbox_get_by_name - Get/request a mailbox by name + * + * This looks up and requests a mailbox channel. The name is relative to the + * client device; each device is assumed to have n mailbox channels associated + * with it somehow, and this function finds and requests one of them. The + * mapping of client device channel names to provider channels may be via + * device-tree properties, board-provided mapping tables, or some other + * mechanism. + * + * @dev: The client device. + * @name: The name of the mailbox channel to request, within the client's + * list of channels. + * @chan A pointer to a channel object to initialize. + * @return 0 if OK, or a negative error code. + */ +int mbox_get_by_name(struct udevice *dev, const char *name, + struct mbox_chan *chan); + +/** + * mbox_free - Free a previously requested mailbox channel. + * + * @chan: A channel object that was previously successfully requested by + * calling mbox_get_by_*(). + * @return 0 if OK, or a negative error code. + */ +int mbox_free(struct mbox_chan *chan); + +/** + * mbox_send - Send a message over a mailbox channel + * + * This function will send a message to the remote entity. It may return before + * the remote entity has received and/or processed the message. + * + * @chan: A channel object that was previously successfully requested by + * calling mbox_get_by_*(). + * @data: A pointer to the message to transfer. The format and size of + * the memory region pointed at by @data is determined by the + * mailbox provider. Providers that solely transfer notifications + * will ignore this parameter. + * @return 0 if OK, or a negative error code. + */ +int mbox_send(struct mbox_chan *chan, const void *data); + +/** + * mbox_recv - Receive any available message from a mailbox channel + * + * This function will wait (up to the specified @timeout_us) for a message to + * be sent by the remote entity, and write the content of any such message + * into a caller-provided buffer. + * + * @chan: A channel object that was previously successfully requested by + * calling mbox_get_by_*(). + * @data: A pointer to the buffer to receive the message. The format and + * size of the memory region pointed at by @data is determined by + * the mailbox provider. Providers that solely transfer + * notifications will ignore this parameter. + * @timeout_us: The maximum time to wait for a message to be available, in + * micro-seconds. A value of 0 does not wait at all. + * @return 0 if OK, -ENODATA if no message was available, or a negative error + * code. + */ +int mbox_recv(struct mbox_chan *chan, void *data, ulong timeout_us); + +#endif diff --git a/include/mailbox_client.h b/include/mailbox_client.h deleted file mode 100644 index 8345ea0bf1..0000000000 --- a/include/mailbox_client.h +++ /dev/null @@ -1,149 +0,0 @@ -/* - * Copyright (c) 2016, NVIDIA CORPORATION. - * - * SPDX-License-Identifier: GPL-2.0 - */ - -#ifndef _MAILBOX_CLIENT_H -#define _MAILBOX_CLIENT_H - -/** - * A mailbox is a hardware mechanism for transferring small fixed-size messages - * and/or notifications between the CPU on which U-Boot runs and some other - * device such as an auxiliary CPU running firmware or a hardware module. - * - * Data transfer is optional; a mailbox may consist solely of a notification - * mechanism. When data transfer is implemented, it is via HW registers or - * FIFOs, rather than via RAM-based buffers. The mailbox API generally - * implements any communication protocol enforced solely by hardware, and - * leaves any higher-level protocols to other layers. - * - * A mailbox channel is a bi-directional mechanism that can send a message or - * notification to a single specific remote entity, and receive messages or - * notifications from that entity. The size, content, and format of such - * messages is defined by the mailbox implementation, or the remote entity with - * which it communicates; there is no general standard at this API level. - * - * A driver that implements UCLASS_MAILBOX is a mailbox provider. A provider - * will often implement multiple separate mailbox channels, since the hardware - * it manages often has this capability. mailbox_uclass.h describes the - * interface which mailbox providers must implement. - * - * Mailbox consumers/clients generate and send, or receive and process, - * messages. This header file describes the API used by clients. - */ - -struct udevice; - -/** - * struct mbox_chan - A handle to a single mailbox channel. - * - * Clients provide storage for channels. The content of the channel structure - * is managed solely by the mailbox API and mailbox drivers. A mailbox channel - * is initialized by "get"ing the mailbox. The channel struct is passed to all - * other mailbox APIs to identify which mailbox to operate upon. - * - * @dev: The device which implements the mailbox. - * @id: The mailbox channel ID within the provider. - * - * Currently, the mailbox API assumes that a single integer ID is enough to - * identify and configure any mailbox channel for any mailbox provider. If this - * assumption becomes invalid in the future, the struct could be expanded to - * either (a) add more fields to allow mailbox providers to store additional - * information, or (b) replace the id field with an opaque pointer, which the - * provider would dynamically allocated during its .of_xlate op, and process - * during is .request op. This may require the addition of an extra op to clean - * up the allocation. - */ -struct mbox_chan { - struct udevice *dev; - /* - * Written by of_xlate. We assume a single id is enough for now. In the - * future, we might add more fields here. - */ - unsigned long id; -}; - -/** - * mbox_get_by_index - Get/request a mailbox by integer index - * - * This looks up and requests a mailbox channel. The index is relative to the - * client device; each device is assumed to have n mailbox channels associated - * with it somehow, and this function finds and requests one of them. The - * mapping of client device channel indices to provider channels may be via - * device-tree properties, board-provided mapping tables, or some other - * mechanism. - * - * @dev: The client device. - * @index: The index of the mailbox channel to request, within the - * client's list of channels. - * @chan A pointer to a channel object to initialize. - * @return 0 if OK, or a negative error code. - */ -int mbox_get_by_index(struct udevice *dev, int index, struct mbox_chan *chan); - -/** - * mbox_get_by_name - Get/request a mailbox by name - * - * This looks up and requests a mailbox channel. The name is relative to the - * client device; each device is assumed to have n mailbox channels associated - * with it somehow, and this function finds and requests one of them. The - * mapping of client device channel names to provider channels may be via - * device-tree properties, board-provided mapping tables, or some other - * mechanism. - * - * @dev: The client device. - * @name: The name of the mailbox channel to request, within the client's - * list of channels. - * @chan A pointer to a channel object to initialize. - * @return 0 if OK, or a negative error code. - */ -int mbox_get_by_name(struct udevice *dev, const char *name, - struct mbox_chan *chan); - -/** - * mbox_free - Free a previously requested mailbox channel. - * - * @chan: A channel object that was previously successfully requested by - * calling mbox_get_by_*(). - * @return 0 if OK, or a negative error code. - */ -int mbox_free(struct mbox_chan *chan); - -/** - * mbox_send - Send a message over a mailbox channel - * - * This function will send a message to the remote entity. It may return before - * the remote entity has received and/or processed the message. - * - * @chan: A channel object that was previously successfully requested by - * calling mbox_get_by_*(). - * @data: A pointer to the message to transfer. The format and size of - * the memory region pointed at by @data is determined by the - * mailbox provider. Providers that solely transfer notifications - * will ignore this parameter. - * @return 0 if OK, or a negative error code. - */ -int mbox_send(struct mbox_chan *chan, const void *data); - -/** - * mbox_recv - Receive any available message from a mailbox channel - * - * This function will wait (up to the specified @timeout_us) for a message to - * be sent by the remote entity, and write the content of any such message - * into a caller-provided buffer. - * - * @chan: A channel object that was previously successfully requested by - * calling mbox_get_by_*(). - * @data: A pointer to the buffer to receive the message. The format and - * size of the memory region pointed at by @data is determined by - * the mailbox provider. Providers that solely transfer - * notifications will ignore this parameter. - * @timeout_us: The maximum time to wait for a message to be available, in - * micro-seconds. A value of 0 does not wait at all. - * @return 0 if OK, -ENODATA if no message was available, or a negative error - * code. - */ -int mbox_recv(struct mbox_chan *chan, void *data, ulong timeout_us); - -#endif diff --git a/include/mailbox_uclass.h b/include/mailbox_uclass.h deleted file mode 100644 index 6a2994c34c..0000000000 --- a/include/mailbox_uclass.h +++ /dev/null @@ -1,83 +0,0 @@ -/* - * Copyright (c) 2016, NVIDIA CORPORATION. - * - * SPDX-License-Identifier: GPL-2.0 - */ - -#ifndef _MAILBOX_UCLASS_H -#define _MAILBOX_UCLASS_H - -/* See mailbox_client.h for background documentation. */ - -#include - -struct udevice; - -/** - * struct mbox_ops - The functions that a mailbox driver must implement. - */ -struct mbox_ops { - /** - * of_xlate - Translate a client's device-tree (OF) mailbox specifier. - * - * The mailbox core calls this function as the first step in - * implementing a client's mbox_get_by_*() call. - * - * If this function pointer is set to NULL, the mailbox core will use - * a default implementation, which assumes #mbox-cells = <1>, and that - * the DT cell contains a simple integer channel ID. - * - * At present, the mailbox API solely supports device-tree. If this - * changes, other xxx_xlate() functions may be added to support those - * other mechanisms. - * - * @chan: The channel to hold the translation result. - * @args: The mailbox specifier values from device tree. - * @return 0 if OK, or a negative error code. - */ - int (*of_xlate)(struct mbox_chan *chan, - struct fdtdec_phandle_args *args); - /** - * request - Request a translated channel. - * - * The mailbox core calls this function as the second step in - * implementing a client's mbox_get_by_*() call, following a successful - * xxx_xlate() call. - * - * @chan: The channel to request; this has been filled in by a - * previoux xxx_xlate() function call. - * @return 0 if OK, or a negative error code. - */ - int (*request)(struct mbox_chan *chan); - /** - * free - Free a previously requested channel. - * - * This is the implementation of the client mbox_free() API. - * - * @chan: The channel to free. - * @return 0 if OK, or a negative error code. - */ - int (*free)(struct mbox_chan *chan); - /** - * send - Send a message over a mailbox channel - * - * @chan: The channel to send to the message to. - * @data: A pointer to the message to send. - * @return 0 if OK, or a negative error code. - */ - int (*send)(struct mbox_chan *chan, const void *data); - /** - * recv - Receive any available message from the channel. - * - * This function does not block. If not message is immediately - * available, the function should return an error. - * - * @chan: The channel to receive to the message from. - * @data: A pointer to the buffer to hold the received message. - * @return 0 if OK, -ENODATA if no message was available, or a negative - * error code. - */ - int (*recv)(struct mbox_chan *chan, void *data); -}; - -#endif