1/* 2 * Copyright 2016, Data61 3 * Commonwealth Scientific and Industrial Research Organisation (CSIRO) 4 * ABN 41 687 119 230. 5 * 6 * This software may be distributed and modified according to the terms of 7 * the BSD 2-Clause license. Note that NO WARRANTY is provided. 8 * See "LICENSE_BSD2.txt" for details. 9 * 10 * @TAG(D61_BSD) 11 */ 12 13#ifndef _SERVER_COMMON_HELPER_LIBRARY_H_ 14#define _SERVER_COMMON_HELPER_LIBRARY_H_ 15 16#include <stdio.h> 17#include <stdlib.h> 18#include <stdint.h> 19#include <stdbool.h> 20#include <sel4/sel4.h> 21#include <refos/refos.h> 22#include <refos-util/dprintf.h> 23#include <refos-util/serv_connect.h> 24#include <refos-rpc/data_client.h> 25#include <refos-rpc/data_client_helper.h> 26#include <refos-rpc/proc_common.h> 27 28/*! @file 29 @brief Server common shared helper functions. 30 31 This module implements helper functions to help reduce the work required to get a RefOS server 32 up and running. It handles the most common setup cases for servers, especially dataspace 33 servers, including endpoint creation, registration, and so forth. 34*/ 35 36#ifndef CONFIG_REFOS_DEBUG 37 #define printf(x,...) 38#endif /* CONFIG_REFOS_DEBUG */ 39 40#define SRV_UNBADGED 0 41#define SRV_DEFAULT_MAX_CLIENTS PROCSERV_MAX_PROCESSES 42#define SRV_DEFAULT_NOTIFICATION_BUFFER_SIZE 0x8000 43#define SRV_DEFAULT_PARAM_BUFFER_SIZE 0x2000 44#define SRV_MAGIC 0x261A2055 45 46#ifndef SET_ERRNO_PTR 47 #define SET_ERRNO_PTR(e, ev) if (e) {(*e) = (ev);} 48#endif 49 50/*! @brief Common server dispatcher message structure. 51 52 Simple structure containing the seL4 message and seL4 badge recieved from the IPC. 53*/ 54typedef struct srv_msg { 55 seL4_MessageInfo_t message; 56 seL4_Word badge; 57} srv_msg_t; 58 59 60/*! @brief Enum to keep track of the common server dispatching return values. */ 61enum srv_dispatch_return_code_enum { 62 DISPATCH_ERROR = -2, /*!< A dispatch error has occured. Should not happen. */ 63 DISPATCH_PASS, /*!< Wrong dispatcher. Pass onto another one. */ 64 DISPATCH_SUCCESS /*!< This is the correct dispatcher, or correctly dispatched. */ 65}; 66 67/*! @brief Common server state configuration. 68 69 This structure stores the server's configuration, including things like name to register under, 70 badge layouts, number of max clients, and so forth. Servers wishing to use this library should 71 fill this config structure with their configuration parameters then pass this into 72 srv_common_init(). 73*/ 74typedef struct srv_common_config { 75 /*! @brief Maximum number of clients in the client table. Set to 0 to disable. */ 76 int maxClients; 77 uint32_t clientBadgeBase; /*!< @brief Client badge number base. */ 78 uint32_t clientMagic; /*!< @brief Client structure magic number identifier. */ 79 80 /*! @brief Size of death / fault notification buffer. Set to 0 to disable. */ 81 int notificationBufferSize; 82 /*! @brief Size of procserv parameter buffer. Set to 0 to disable. */ 83 int paramBufferSize; 84 85 /*! @brief Server name, used for debug printing. */ 86 char* serverName; 87 /*! @brief Server registration mountpoint. NULL to disable registration. */ 88 char* mountPointPath; 89 /*! @brief Server registration parent nameserver, to register under. */ 90 seL4_CPtr nameServEP; 91 92 /*! @brief Fault / death async notification badge number. */ 93 uint32_t faultDeathNotifyBadge; 94} srv_common_config_t; 95 96struct srv_common; 97typedef struct srv_common srv_common_t; 98 99/*! @brief Common server state structure. */ 100struct srv_common { 101 uint32_t magic; 102 srv_common_config_t config; 103 104 /* Endpoints and badges. */ 105 seL4_CPtr anonEP; 106 seL4_CPtr notifyAsyncEP; 107 seL4_CPtr notifyClientFaultDeathAsyncEP; 108 109 /* Mapped shared buffers. */ 110 data_mapping_t notifyBuffer; 111 size_t notifyBufferStart; 112 data_mapping_t procServParamBuffer; 113 114 /* Client table structure. */ 115 struct srv_client_table clientTable; 116 117 /* Default client table handlers. These should provide a simple default implementation for 118 the serv interface defined in the generated <refos-rpc/serv_server.h>. */ 119 120 struct srv_client* (*ctable_connect_direct_handler) (srv_common_t *srv, srv_msg_t *m, 121 seL4_CPtr liveness, int* _errno); 122 123 refos_err_t (*ctable_set_param_buffer_handler) (srv_common_t *srv, struct srv_client *c, 124 srv_msg_t *m, seL4_CPtr parambufferDataspace, uint32_t parambufferSize); 125 126 void (*ctable_disconnect_direct_handler) (srv_common_t *srv, struct srv_client *c); 127}; 128 129/*! @brief Notification handler callback type. */ 130typedef int (*srv_notify_handler_callback_fn_t)(struct proc_notification *notification); 131 132/*! @brief Notification handler callbacks structure. */ 133typedef struct srv_common_notify_handler_callbacks { 134 srv_notify_handler_callback_fn_t handle_server_fault; 135 srv_notify_handler_callback_fn_t handle_server_content_init; 136 srv_notify_handler_callback_fn_t handle_server_death_notification; 137} srv_common_notify_handler_callbacks_t; 138 139/*! @brief Initialise server common state. 140 @param s The common server state structure to initialise. 141 @param config The structure containing info on server configuration. 142 @return ESUCCESS on success, refos_err_t error otherwise. 143*/ 144int srv_common_init(srv_common_t *s, srv_common_config_t config); 145 146/*! @brief Helper function to mint a badged server endpoint cap. 147 @param badge The badge ID to mint. 148 @param ep The endpoint to mint from. 149 @return The minted capability (Ownership transferred). 150*/ 151seL4_CPtr srv_mint(int badge, seL4_CPtr ep); 152 153/*! @brief Helper function to check recieved caps and unwrapped mask. 154 @param m The recieved message. 155 @param unwrappedMask The expected capability unwrap mask. 156 @param numExtraCaps The expected nubmer of recieved capabilities. 157 @return true if the recieved message capabilities match the unwrapped mask and number, false 158 if there is a mismatck and the recieved caps are invalid. 159*/ 160bool srv_check_dispatch_caps(srv_msg_t *m, seL4_Word unwrappedMask, int numExtraCaps); 161 162/*! @brief Server notification dispatcher helper. 163 164 The goal of this helper function is to remove the common shared ringbuffer notification reading 165 and handling routines used by servers wishing to recieve async notifications. When a message 166 is read from the given server state's notification buffer, then the corresponding callback 167 handler function pointer is called. 168 169 @param srv The server common state structure. (No ownership) 170 @param callbacks Struct containing callbacks, one for each possible type of notification. 171 If the given server does not handle a certain type of notification, simply 172 set the corresponding callback as NULL. 173 @return ESUCCESS on success, refos_err_t error otherwise. 174*/ 175int srv_dispatch_notification(srv_common_t *srv, srv_common_notify_handler_callbacks_t callbacks); 176 177#endif /* _SERVER_COMMON_HELPER_LIBRARY_H_ */