1.. zephyr:code-sample:: userspace_prod_consumer
2   :name: Producer/consumer
3
4   Manipulate basic user mode concepts.
5
6Overview
7********
8
9Consider a "sample driver" which gets incoming data from some unknown source
10and generates interrupts with pointers to this data. The application needs
11to perform some processing on this data and then write the processed data
12back to the driver.
13
14The goal here is to demonstrate:
15
16 - Multiple logical applications, each with their own memory domain
17 - Creation of a sys_heap and assignment to a memory partition
18 - Use of APIs like ``k_queue_alloc_append()`` which require thread resource
19   pools to be configured
20 - Management of permissions for kernel objects and drivers
21 - Show how application-specific system calls are defined
22 - Show IPC between ISR and application (using ``k_msgq``) and
23   application-to-application IPC (using ``k_queue``)
24 - Show how to create application-specific system calls
25
26In this example, we have an Application A whose job is to talk to the
27driver, buffer incoming data, and write it back once processed by
28Application B.
29
30Application B simply processes the data. Let's pretend this data is
31untrusted and possibly malicious, so Application B is sandboxed from
32everything else, with just two queues for sending/receiving data items.
33
34The control loop is as follows:
35
36 - Sample driver issues interrupts, invoking its associated callback
37   function with a fixed-sized data payload.
38 - App A callback function, in supervisor mode, places the data payload
39   into a message queue.
40 - App A monitor thread in user mode waits for data in the message queue.
41   When it wakes up, copy the data payload into a buffer allocated out
42   of the shared memory pool, and enqueue this data into a ``k_queue`` being
43   monitored by application B.
44 - Application B processing thread waits on new items in the queue. It
45   then processes the data in-place, and after it's finished it places
46   the processed data into another queue to be written back to the driver.
47 - Application A writeback thread monitors the outgoing data queue for
48   new items containing processed data. As it gets them it will write
49   such data back to the driver and free the buffer.
50
51We also demonstrate application-defined system calls, in the form of
52the ``magic_cookie()`` function.
53
54Sample Output
55*************
56
57.. code-block:: console
58
59    I:APP A partition: 0x00110000 4096
60    I:Shared partition: 0x0010e000 4096
61    I:sample_driver_foo_isr: param=0x00147078 count=0
62    I:monitor thread got data payload #0
63    I:sample_driver_foo_isr: param=0x00147078 count=1
64    I:monitor thread got data payload #1
65    I:sample_driver_foo_isr: param=0x00147078 count=2
66    I:monitor thread got data payload #2
67    I:sample_driver_foo_isr: param=0x00147078 count=3
68    I:monitor thread got data payload #3
69    I:sample_driver_foo_isr: param=0x00147078 count=4
70    I:monitor thread got data payload #4
71    I:processing payload #1 complete
72    I:writing processed data blob back to the sample device
73    I:sample_driver_foo_isr: param=0x00147078 count=5
74    I:monitor thread got data payload #5
75    I:processing payload #2 complete
76    I:writing processed data blob back to the sample device
77    I:sample_driver_foo_isr: param=0x00147078 count=6
78    I:monitor thread got data payload #6
79    I:processing payload #3 complete
80    I:writing processed data blob back to the sample device
81    I:sample_driver_foo_isr: param=0x00147078 count=7
82    I:monitor thread got data payload #7
83    I:processing payload #4 complete
84    I:writing processed data blob back to the sample device
85    I:sample_driver_foo_isr: param=0x00147078 count=8
86    I:monitor thread got data payload #8
87    I:processing payload #5 complete
88    I:writing processed data blob back to the sample device
89    I:sample_driver_foo_isr: param=0x00147078 count=9
90    I:monitor thread got data payload #9
91    I:processing payload #6 complete
92    I:writing processed data blob back to the sample device
93    I:processing payload #7 complete
94    I:writing processed data blob back to the sample device
95    I:processing payload #8 complete
96    I:writing processed data blob back to the sample device
97    I:processing payload #9 complete
98    I:writing processed data blob back to the sample device
99    I:processing payload #10 complete
100    I:writing processed data blob back to the sample device
101    I:SUCCESS
102