1 /* 2 * Interprocess communication message abstraction. 3 * 4 * Copyright (C) 2018, 2019, 2021, 2022, 2024 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/sys/ipc.h> 25 #include <l4/sys/utcb.h> 26 #include <l4/sys/types.h> 27 28 #include <sys/types.h> 29 30 31 32 EXTERN_C_BEGIN 33 34 /* Message abstraction. */ 35 36 typedef struct 37 { 38 /* Common virtual registers. */ 39 40 l4_buf_regs_t bregs; 41 l4_msg_regs_t mregs; 42 43 /* Input details. */ 44 45 l4_msgtag_t tag; 46 unsigned int expected_items; 47 48 /* Receive item counter. */ 49 50 unsigned int receive_items; 51 52 /* Imported item counter. */ 53 54 unsigned int import_item; 55 56 /* Output details. */ 57 58 unsigned int words; 59 unsigned int items; 60 61 /* Items transferred and not retained. */ 62 63 unsigned int discarded_items; 64 l4_cap_idx_t to_discard[L4_UTCB_GENERIC_DATA_SIZE]; 65 66 /* Message label overriding. */ 67 68 l4_umword_t new_label; 69 70 /* Server control. */ 71 72 int terminating; 73 74 } ipc_message_t; 75 76 77 78 /* Special status codes. */ 79 80 #define IPC_MESSAGE_SENT 0x01d10000 81 82 /* Capability annotations. */ 83 84 #define IPC_DISCARD_CAP_FLAG (1 << (L4_CAP_SHIFT - 2)) 85 #define discard_cap(x) (x | IPC_DISCARD_CAP_FLAG) 86 87 88 89 /* Message operations. */ 90 91 /* Lifecycle operations. */ 92 93 void ipc_message_new(ipc_message_t *msg); 94 long ipc_message_expect(ipc_message_t *msg, unsigned int expected_items); 95 void ipc_message_request(ipc_message_t *msg, int op, l4_cap_idx_t endpoint); 96 void ipc_message_send(ipc_message_t *msg, int op, l4_cap_idx_t endpoint); 97 void ipc_message_wait(ipc_message_t *msg, l4_umword_t *label); 98 void ipc_message_reply(ipc_message_t *msg); 99 void ipc_message_discard(ipc_message_t *msg); 100 void ipc_message_free(ipc_message_t *msg); 101 102 /* Helper operations. */ 103 104 void ipc_message_open(ipc_message_t *msg); 105 void ipc_message_prepare(ipc_message_t *msg); 106 void ipc_message_preserve_buffer_registers(ipc_message_t *msg); 107 void ipc_message_preserve_message_registers(ipc_message_t *msg); 108 void ipc_message_reset(ipc_message_t *msg); 109 void ipc_message_restore_buffer_registers(ipc_message_t *msg); 110 void ipc_message_restore_message_registers(ipc_message_t *msg); 111 112 /* Population operations. */ 113 114 void ipc_message_add_capability(ipc_message_t *msg, l4_cap_idx_t cap); 115 void ipc_message_add_data(ipc_message_t *msg, const char *value, size_t length); 116 void ipc_message_add_item(ipc_message_t *msg, l4_cap_idx_t cap); 117 void ipc_message_add_fpage(ipc_message_t *msg, l4_snd_fpage_t fpage); 118 void ipc_message_add_page(ipc_message_t *msg, l4_umword_t hot_spot, l4_fpage_t fpage); 119 void ipc_message_add_receive_capability(ipc_message_t *msg, l4_cap_idx_t /* cap */); 120 void ipc_message_add_receive_fpage(ipc_message_t *msg, l4_snd_fpage_t fpage); 121 void ipc_message_add_string(ipc_message_t *msg, const char *value); 122 void ipc_message_add_word(ipc_message_t *msg, l4_umword_t value); 123 void ipc_message_propagate_item(ipc_message_t *msg, l4_cap_idx_t cap); 124 void *ipc_message_reserve_data(ipc_message_t *msg, size_t length); 125 void *ipc_message_reserve_words(ipc_message_t *msg, size_t length); 126 void ipc_message_send_error(ipc_message_t *msg, long error); 127 128 /* Access operations. */ 129 130 l4_umword_t ipc_message_get_word(ipc_message_t *msg, unsigned int word); 131 l4_umword_t *ipc_message_get_word_address(ipc_message_t *msg, unsigned int word); 132 unsigned int ipc_message_number_of_items(ipc_message_t *msg); 133 unsigned int ipc_message_number_of_words(ipc_message_t *msg); 134 135 /* Supporting operations. */ 136 137 void ipc_message_discard_capability(ipc_message_t *msg, l4_cap_idx_t cap); 138 void ipc_message_discard_dataspace(ipc_message_t *msg, l4_cap_idx_t mem, l4_addr_t addr); 139 long ipc_message_expect_capabilities(ipc_message_t *msg, int number); 140 long ipc_message_expect_capability(ipc_message_t *msg, int item); 141 void ipc_message_export_capability(ipc_message_t *msg, int item, l4_cap_idx_t ref); 142 void ipc_message_export_fpage(ipc_message_t *msg, int item, l4_snd_fpage_t fpage); 143 void ipc_message_export_page(ipc_message_t *msg, int item, l4_umword_t hot_spot, l4_fpage_t fpage); 144 long ipc_message_import_and_expect_capability(ipc_message_t *msg, int item, l4_cap_idx_t *ref); 145 long ipc_message_import_and_expect_dataspace(ipc_message_t *msg, int item, l4_cap_idx_t *mem, l4_addr_t *addr); 146 long ipc_message_import_capability(ipc_message_t *msg, int item, l4_cap_idx_t *ref); 147 long ipc_message_import_dataspace(ipc_message_t *msg, int item, l4_cap_idx_t *mem, l4_addr_t *addr); 148 long ipc_message_import_fpage(ipc_message_t *msg, int item, l4_snd_fpage_t *fpage); 149 void ipc_message_propagate_capability(ipc_message_t *msg, int item, l4_cap_idx_t ref); 150 void ipc_message_receive_fpage(ipc_message_t *msg, int item, l4_snd_fpage_t fpage); 151 l4_msgtag_t ipc_message_reply_tag(ipc_message_t *msg); 152 l4_msgtag_t ipc_message_request_tag(ipc_message_t *msg, int op); 153 154 EXTERN_C_END 155 156 /* vim: tabstop=2 expandtab shiftwidth=2 157 */