1# Remoteproc Design Document 2Remoteproc provides abstraction to manage the life cycle of a remote 3application. For now, it only provides APIs on bringing up and 4tearing down the remote application, and parsing resource table. 5It will extend to crash detection, suspend and resume. 6 7## Remoteproc LCM States 8| State | State Description | 9|:------|:------------------| 10| Offline | Initial state of a remoteproc instance. The remote presented by the remoteproc instance and its resource has been powered off. | 11| Configured | The remote presented by the remoteproc instance has been configured. And ready to load applicaiton. | 12| Ready | The remote presented by the remoteproc instance has applicaiton loaded, and ready to run. | 13| Stopped | The remote presented by the remoteproc instance has stopped from running. But the remote is still powered on. And the remote's resource hasn't been released. | 14 15 16 17### State Transition 18| State Transition | Transition Trigger | 19|:-----------------|:-------------------| 20| Offline -> Configured | Configure the remote to make it able to load application;<br>`remoteproc_configure(&rproc, &config_data)`| 21| Configured -> Ready | load firmware ;<br>`remoteproc_load(&rproc, &path, &image_store, &image_store_ops, &image_info)` | 22| Ready -> Running | start the processor; <br>`remoteproc_start(&rproc)` | 23| Ready -> Stopped | stop the processor; <br>`remoteproc_stop(&rproc)`; <br>`remoteproc_shutdown(&rproc)`(Stopped is the intermediate state of shutdown operation) | 24| Running -> Stopped | stop the processor; <br>`remoteproc_stop(&rproc)`; <br>`remoteproc_shutdown(&rproc)` | 25| Stopped -> Offline | shutdown the processor; <br>`remoteproc_shutdown(&rproc)` | 26 27## Remote User APIs 28* Initialize remoteproc instance: 29 ``` 30 struct remoteproc *remoteproc_init(struct remoteproc *rproc, 31 struct remoteproc_ops *ops, void *priv) 32 ``` 33* Release remoteproc instance: 34 ``` 35 int remoteproc_remove(struct remoteproc *rproc) 36 ``` 37* Add memory to remoteproc: 38 ``` 39 void remoteproc_add_mem(struct remoteproc *rproc, struct remoteproc_mem *mem) 40 ``` 41* Get memory libmetal I/O region from remoteproc specifying memory name: 42 ``` 43 struct metal_io_region *remoteproc_get_io_with_name(struct remoteproc *rproc, const char *name) 44 ``` 45* Get memory libmetal I/O region from remoteproc specifying physical address: 46 ``` 47 struct metal_io_region *remoteproc_get_io_with_pa(struct remoteproc *rproc, metal_phys_addr_t pa); 48 ``` 49* Get memory libmetal I/O region from remoteproc specifying virtual address: 50 ``` 51 struct metal_io_region *remoteproc_get_io_with_va(struct remoteproc *rproc, void *va); 52 ``` 53* Map memory and add the memory to the remoteproc instance: 54 ``` 55 void *remoteproc_mmap(struct remoteproc *rproc, 56 metal_phys_addr_t *pa, metal_phys_addr_t *da, 57 size_t size, unsigned int attribute, 58 struct metal_io_region **io); 59 ``` 60* Set resource table to remoteproc: 61 ``` 62 int remoteproc_set_rsc_table(struct remoteproc *rproc, 63 struct resource_table *rsc_table, 64 size_t rsc_size) 65 ``` 66* Configure the remote presented by the remoteproc instance to make it able 67 to load applicaiton: 68 ``` 69 int remoteproc_config(struct remoteproc *rproc, void *data) 70 ``` 71* Load application to the remote presented by the remoteproc instance to make 72 it ready to run: 73 ``` 74 int remoteproc_load(struct remoteproc *rproc, const char *path, 75 void *store, struct image_store_ops *store_ops, 76 void **img_info) 77 ``` 78* Run application on the remote presented by the remoteproc instance: 79 ``` 80 int remoteproc_start(struct remoteproc *rproc) 81 ``` 82* Stop application on remote presented by the remoteproc instance: 83 ``` 84 int remoteproc_stop(struct remoteproc *rproc) 85 ``` 86* Shutdown the remote presented by the remoteproc instance: 87 ``` 88 int remoteproc_shutdown(struct remoteproc *rproc) 89 ``` 90* Create virtio device from the resource table vdev resource, and add it to the 91 remoteproc instance: 92 ``` 93 struct virtio_device *remoteproc_create_virtio(struct remoteproc *rproc, 94 int vdev_id, unsigned int role, 95 void (*rst_cb)(struct virtio_device *vdev)) 96 ``` 97* Remove virtio device from the remoteproc instance: 98 ``` 99 void remoteproc_remove_virtio(struct remoteproc *rproc, 100 struct virtio_device *vdev) 101 ``` 102 103 104
