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