Documentation/driver-api/mailbox.rst

Source file repositories/reference/linux-study-clean/Documentation/driver-api/mailbox.rst

File Facts

System
Linux kernel
Corpus path
Documentation/driver-api/mailbox.rst
Extension
.rst
Size
4438 bytes
Lines
130
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct demo_client {
		struct mbox_client cl;
		struct mbox_chan *mbox;
		struct completion c;
		bool async;
		/* ... */
	};

	/*
	* This is the handler for data received from remote. The behaviour is purely
	* dependent upon the protocol. This is just an example.
	*/
	static void message_from_remote(struct mbox_client *cl, void *mssg)
	{
		struct demo_client *dc = container_of(cl, struct demo_client, cl);
		if (dc->async) {
			if (is_an_ack(mssg)) {
				/* An ACK to our last sample sent */
				return; /* Or do something else here */
			} else { /* A new message from remote */
				queue_req(mssg);
			}
		} else {
			/* Remote f/w sends only ACK packets on this channel */
			return;
		}
	}

	static void sample_sent(struct mbox_client *cl, void *mssg, int r)
	{
		struct demo_client *dc = container_of(cl, struct demo_client, cl);
		complete(&dc->c);
	}

	static void client_demo(struct platform_device *pdev)
	{
		struct demo_client *dc_sync, *dc_async;
		/* The controller already knows async_pkt and sync_pkt */
		struct async_pkt ap;
		struct sync_pkt sp;

		dc_sync = kzalloc_obj(*dc_sync);
		dc_async = kzalloc_obj(*dc_async);

		/* Populate non-blocking mode client */
		dc_async->cl.dev = &pdev->dev;
		dc_async->cl.rx_callback = message_from_remote;
		dc_async->cl.tx_done = sample_sent;
		dc_async->cl.tx_block = false;
		dc_async->cl.tx_tout = 0; /* doesn't matter here */
		dc_async->cl.knows_txdone = false; /* depending upon protocol */
		dc_async->async = true;
		init_completion(&dc_async->c);

		/* Populate blocking mode client */
		dc_sync->cl.dev = &pdev->dev;
		dc_sync->cl.rx_callback = message_from_remote;
		dc_sync->cl.tx_done = NULL; /* operate in blocking mode */
		dc_sync->cl.tx_block = true;
		dc_sync->cl.tx_tout = 500; /* by half a second */
		dc_sync->cl.knows_txdone = false; /* depending upon protocol */
		dc_sync->async = false;

		/* ASync mailbox is listed second in 'mboxes' property */
		dc_async->mbox = mbox_request_channel(&dc_async->cl, 1);
		/* Populate data packet */
		/* ap.xxx = 123; etc */
		/* Send async message to remote */
		mbox_send_message(dc_async->mbox, &ap);

Annotation

Implementation Notes