1 /* 2 * Interprocess communication message abstraction. 3 * 4 * Copyright (C) 2018, 2019, 2021, 2022 Paul Boddie <paul@boddie.org.uk> 5 * 6 * This program is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU General Public License as 8 * published by the Free Software Foundation; either version 2 of 9 * the License, or (at your option) any later version. 10 * 11 * This program is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 * GNU General Public License for more details. 15 * 16 * You should have received a copy of the GNU General Public License 17 * along with this program; if not, write to the Free Software 18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, 19 * Boston, MA 02110-1301, USA 20 */ 21 22 #pragma once 23 24 #include <l4/re/c/dataspace.h> 25 #include <l4/sys/ipc.h> 26 #include <l4/sys/utcb.h> 27 #include <l4/sys/types.h> 28 29 #include <sys/types.h> 30 31 32 33 EXTERN_C_BEGIN 34 35 /* Message abstraction. */ 36 37 typedef struct 38 { 39 /* Common virtual registers. */ 40 41 l4_buf_regs_t bregs; 42 l4_msg_regs_t mregs; 43 44 /* Input details. */ 45 46 l4_msgtag_t tag; 47 unsigned int expected_items; 48 49 /* Receive item counter. */ 50 51 unsigned int receive_items; 52 53 /* Output details. */ 54 55 unsigned int words; 56 unsigned int items; 57 58 /* Items transferred and not retained. */ 59 60 unsigned int discarded_items; 61 l4_cap_idx_t to_discard[L4_UTCB_GENERIC_DATA_SIZE]; 62 63 /* Message label overriding. */ 64 65 l4_umword_t new_label; 66 67 /* Server control. */ 68 69 int terminating; 70 71 } ipc_message_t; 72 73 74 75 /* Special status codes. */ 76 77 #define IPC_MESSAGE_SENT 0x01d10000 78 79 /* Capability annotations. */ 80 81 #define IPC_DISCARD_CAP_FLAG (1 << (L4_CAP_SHIFT - 2)) 82 #define discard_cap(x) (x | IPC_DISCARD_CAP_FLAG) 83 84 85 86 /* Message operations. */ 87 88 /* Lifecycle operations. */ 89 90 void ipc_message_new(ipc_message_t *msg); 91 long ipc_message_expect(ipc_message_t *msg, unsigned int expected_items); 92 void ipc_message_request(ipc_message_t *msg, int op, l4_cap_idx_t endpoint); 93 void ipc_message_send(ipc_message_t *msg, int op, l4_cap_idx_t endpoint); 94 void ipc_message_wait(ipc_message_t *msg, l4_umword_t *label); 95 void ipc_message_reply(ipc_message_t *msg); 96 void ipc_message_discard(ipc_message_t *msg); 97 void ipc_message_free(ipc_message_t *msg); 98 99 /* Helper operations. */ 100 101 void ipc_message_open(ipc_message_t *msg); 102 void ipc_message_prepare(ipc_message_t *msg); 103 void ipc_message_preserve_buffer_registers(ipc_message_t *msg); 104 void ipc_message_preserve_message_registers(ipc_message_t *msg); 105 void ipc_message_reset(ipc_message_t *msg); 106 void ipc_message_restore_buffer_registers(ipc_message_t *msg); 107 void ipc_message_restore_message_registers(ipc_message_t *msg); 108 109 /* Population operations. */ 110 111 void ipc_message_add_capability(ipc_message_t *msg, l4_cap_idx_t cap); 112 void ipc_message_add_data(ipc_message_t *msg, const char *value, size_t length); 113 void ipc_message_add_item(ipc_message_t *msg, l4_cap_idx_t cap); 114 void ipc_message_add_fpage(ipc_message_t *msg, l4_snd_fpage_t fpage); 115 void ipc_message_add_page(ipc_message_t *msg, l4_umword_t hot_spot, l4_fpage_t fpage); 116 void ipc_message_add_receive_fpage(ipc_message_t *msg, l4_snd_fpage_t fpage); 117 void ipc_message_add_string(ipc_message_t *msg, const char *value); 118 void ipc_message_add_word(ipc_message_t *msg, l4_umword_t value); 119 void ipc_message_propagate_item(ipc_message_t *msg, l4_cap_idx_t cap); 120 void *ipc_message_reserve_data(ipc_message_t *msg, size_t length); 121 void *ipc_message_reserve_words(ipc_message_t *msg, size_t length); 122 void ipc_message_send_error(ipc_message_t *msg, long error); 123 124 /* Access operations. */ 125 126 l4_umword_t ipc_message_get_word(ipc_message_t *msg, unsigned int word); 127 l4_umword_t *ipc_message_get_word_address(ipc_message_t *msg, unsigned int word); 128 unsigned int ipc_message_number_of_items(ipc_message_t *msg); 129 unsigned int ipc_message_number_of_words(ipc_message_t *msg); 130 131 /* Supporting operations. */ 132 133 void ipc_message_discard_capability(ipc_message_t *msg, l4_cap_idx_t cap); 134 void ipc_message_discard_dataspace(ipc_message_t *msg, l4re_ds_t mem, l4_addr_t addr); 135 long ipc_message_expect_capabilities(ipc_message_t *msg, int number); 136 long ipc_message_expect_capability(ipc_message_t *msg, int item); 137 void ipc_message_export_capability(ipc_message_t *msg, int item, l4_cap_idx_t ref); 138 void ipc_message_export_fpage(ipc_message_t *msg, int item, l4_snd_fpage_t fpage); 139 void ipc_message_export_page(ipc_message_t *msg, int item, l4_umword_t hot_spot, l4_fpage_t fpage); 140 long ipc_message_import_capability(ipc_message_t *msg, int item, l4_cap_idx_t *ref); 141 long ipc_message_import_dataspace(ipc_message_t *msg, int item, l4re_ds_t *mem, l4_addr_t *addr); 142 long ipc_message_import_fpage(ipc_message_t *msg, int item, l4_snd_fpage_t *fpage); 143 void ipc_message_propagate_capability(ipc_message_t *msg, int item, l4_cap_idx_t ref); 144 void ipc_message_receive_fpage(ipc_message_t *msg, int item, l4_snd_fpage_t fpage); 145 l4_msgtag_t ipc_message_reply_tag(ipc_message_t *msg); 146 l4_msgtag_t ipc_message_request_tag(ipc_message_t *msg, int op); 147 148 EXTERN_C_END